@ -10,7 +10,7 @@ Today, in 2021, the Lightning Network is still in its infancy. The Lightning Net
The concept of the Lightning Network was proposed in 2015, and the first implementation was launched in 2018. As of 2021, we're only beginning to see the opportunities the Lightning Network provides to Bitcoin, including improved privacy, speed, and scale.
With core knowledge of the Lightning Network, you can help shape the future of the network while also building opportunities for yourself.
We assume you already have some basic knowledge about Bitcoin, but if not, don't worry—we will explain the most important Bitcoin concepts, those you must know to understand the Lightning Network, in <<bitcoin_fundamentals_review>>. If you want to learn more about Bitcoin, you can read _Mastering Bitcoin_, 2nd edition, by Andreas M. Antonopoulos (O'Reilly), available https://bitcoinbook.info/[for free online].
We assume you already have some basic knowledge about Bitcoin, but if not, don't worry—we will explain the most important Bitcoin concepts, those you must know to understand the Lightning Network, in <<bitcoin_fundamentals_review>>. If you want to learn more about Bitcoin, you can read _Mastering Bitcoin_, 2nd edition, by Andreas M. Antonopoulos (O'Reilly), available https://github.com/bitcoinbook/bitcoinbook[for free online].
While the bulk of this book is written for programmers, the first few chapters are written to be approachable by anyone regardless of technical experience. In this chapter, we'll start with some terminology, then move to look at trust and its application in these systems, and finally we'll discuss the history and future of the Lightning Network. Let's get started.
@ -747,7 +747,7 @@ As a Lightning node operator, one of the recurring tasks you will need to perfor
As soon as you get your Lightning node up and running, you can fund its Bitcoin wallet and then start opening channels with those funds.
You must choose channel partners carefully because your node's ability to send payments depends on who your channel partners are and how well connected they are to the rest of the Lightning Network. You also want to have more than one channel to avoid being susceptible to a single point of failure. Since Lightning now supports multipath payments, you can split your initial funds into several channels and route bigger payments by combining their capacity. At the same time, avoid making your channels too small. Since you need to pay Bitcoin transaction fees to open and close a channel, the channel balance should not be so small that the on-chain fees consume a significant portion. It's all about balance!
You must choose channel partners carefully because your node's ability to send payments depends on who your channel partners are and how well connected they are to the rest of the Lightning Network. You also want to have more than one channel to avoid being susceptible to a single point of failure. Since Lightning now supports multipart payments, you can split your initial funds into several channels and route bigger payments by combining their capacity. At the same time, avoid making your channels too small. Since you need to pay Bitcoin transaction fees to open and close a channel, the channel balance should not be so small that the on-chain fees consume a significant portion. It's all about balance!
To summarize:
@ -800,7 +800,7 @@ The autopilot will make channel recommendations whenever the conditions are met
According to the preceding configuration file, the channels will be between 5 mBTC (minchansize = 500,000 satoshi) and 50 mBTC (maxchansize = 5,000,000 satoshi) in size.
As is common, the amounts in the configuration file are enumerated in satoshi.
Currently, channels below 1 mBTC are not very useful, and we do not recommend you open channels that are too small and below this amount.
With the wider adoption of multipath payments, smaller channels are less of a burden. But for the time being, this is our recommendation.
With the wider adoption of multipart payments, smaller channels are less of a burden. But for the time being, this is our recommendation.
The +c-lightning+ plug-in, which was originally written by René Pickhardt (a coauthor of this book), works very differently in comparison with the +lnd+ autopilot.
First, it differs in the algorithms used to make the recommendations. We will not cover this here. Secondly, it differs in its user interface.
In this chapter we will bring together payment channels and Hash Time-Locked Contracts (HTLCs). In <<payment_channels>> we explained the way Alice and Bob construct a payment channel between their two nodes. We also looked at the commitment and penalty mechanisms that secure the payment channel. In <<routing>> we looked at Hash Time-Locked Contracts (HTLCs) and how these can be used to route a payment across a path made of multiple payment channels. In this chapter we bring the two concepts together by looking at how HTLCs are managed on each payment channel, how the HTLCs are committed to the channel state and how they are settled to update the channel balances.
In this chapter we will bring together payment channels and Hash Time-Locked Contracts (HTLCs). In <<payment_channels>> we explained the way Alice and Bob construct a payment channel between their two nodes. We also looked at the commitment and penalty mechanisms that secure the payment channel. In <<routing>> we looked at Hash Time-Locked Contracts (HTLCs) and how these can be used to route a payment across a path made of multiple payment channels. In this chapter we bring the two concepts together by looking at how HTLCs are managed on each payment channel, how the HTLCs are committed to the channel state, and how they are settled to update the channel balances.
Specifically, we will be discussing "Adding, Settling, Failing HTLCs" and the "Channel State Machine" that form the overlap between the Peer 2 Peer layer and the Routing layer, as highlighted by a double outline in <<LN_protocol_channelops_highlight>>:
Specifically, we will be discussing "Adding, Settling, Failing HTLCs" and the "Channel State Machine" that form the overlap between the Peer-2-Peer layer and the Routing layer, as highlighted by a double outline in <<LN_protocol_channelops_highlight>>.
=== Local (Single Channel) vs. Routed (Multiple Channels)
=== Local (Single Channel) versus Routed (Multiple Channels)
Even though it is possible to send payments across a payment channel simply by updating the channel balances and creating new commitment transactions, the Lightning protocol uses HTLCs even for "local" payments across a payment channel. The reason for this is to maintain the same protocol design regardless of whether a payment is only one hop (across a single payment channel), or several hops (routed across multiple payment channels).
By maintaining the same abstraction for both local and remote, we not only simplify the protocol design but we also improve privacy. For the recipient of a payment there is no discernible difference between a payment made directly by their channel partner and a payment forwarded by their channel partner on behalf of someone else.
By maintaining the same abstraction for both local and remote, we not only simplify the protocol design but also improve privacy. For the recipient of a payment there is no discernible difference between a payment made directly by their channel partner and a payment forwarded by their channel partner on behalf of someone else.
=== Forwarding Payments and Updating Commitments with HTLCs
We will revisit our example from <<routing>>, to demonstrate how the HTLCs from Alice to Dina gets committed to each payment channel. As you recall in our example, Alice is paying Dina 50,000 satoshis, by routing an HTLC via Bob and Chan. The network is shown in <<alice_dina_htlc_2>> below:
We will revisit our example from <<routing>> to demonstrate how the HTLCs from Alice to Dina get committed to each payment channel. As you recall in our example, Alice is paying Dina 50,000 satoshis by routing an HTLC via Bob and Chan. The network is shown in <<alice_dina_htlc_2>>.
[[alice_dina_htlc_2]]
.Alice pays Dina with an HTLC routed via Bob and Chan
@ -28,19 +28,19 @@ We will focus on the payment channel between Alice and Bob and review the messag
==== HTLC and Commitment Message Flow
The message flow between Alice and Bob (and also between any pair of channel partners) is shown in <<HTLC_commitment_message_flow>>:
The message flow between Alice and Bob (and also between any pair of channel partners) is shown in <<HTLC_commitment_message_flow>>.
[[HTLC_commitment_message_flow]]
.The message flow for HTLC commitment between channel partners
image::images/mtln_0903.png["The message flow for HTLC commitment between channel partners"]
We've already seen the +commitment_signed+ and +revoke_and_ack+ in <<payment_channels>>. Now we will see how HTLCs fit into the commitment scheme. The two new messages are +update_add_htlc+ which Alice uses to ask Bob to add an HTLC and +update_fulfill_htlc+ which Bob uses to redeem the HTLC once he has received the payment secret (Dina's secret).
We've already seen the +commitment_signed+ and +revoke_and_ack+ in <<payment_channels>>. Now we will see how HTLCs fit into the commitment scheme. The two new messages are +update_add_htlc+, which Alice uses to ask Bob to add an HTLC, and +update_fulfill_htlc+, which Bob uses to redeem the HTLC once he has received the payment secret (Dina's secret).
=== Forwarding Payments with HTLCs
Alice and Bob start with a payment channel that has 70,000 satoshi balance on each side.
Alice and Bob start with a payment channel that has a 70,000 satoshi balance on each side.
As we saw in <<payment_channels>> this means that Alice and Bob have negotiated and each hold commitment transactions. These commitment transactions are asymmetric, delayed and revocable, and look like the example in <<alice_bob_commitment_txs_1>> below:
As we saw in <<payment_channels>>, this means that Alice and Bob have negotiated and each hold commitment transactions. These commitment transactions are asymmetric, delayed, and revocable, and look like the example in <<alice_bob_commitment_txs_1>>.
[[alice_bob_commitment_txs_1]]
.Alice and Bob's initial commitment transactions
@ -55,10 +55,10 @@ To add the HTLC, Alice starts the flow we saw in <<HTLC_commitment_message_flow>
[[update_add_htlc]]
==== The update_add_HTLC Message
Alice sends the `update_add_HTLC` Lightning message to Bob. This message is defined in https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md#adding-an-htlc-update_add_htlc[BOLT #2 - Peer Protocol - update_add_HTLC], and is shown below:
Alice sends the `update_add_HTLC` Lightning message to Bob. This message is defined in https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md#adding-an-htlc-update_add_htlc[BOLT #2-Peer Protocol -update_add_HTLC], and is shown in Example 9-1.
[[update_add_HTLC_message_fields]]
.The update_add_HTLC message
.The `update_add_HTLC` message
====
----
[channel_id:channel_id]
@ -72,13 +72,13 @@ Alice sends the `update_add_HTLC` Lightning message to Bob. This message is defi
+channel_id+:: This is the channel that Alice has with Bob that she wants to add the HTLC. Remember that Alice and Bob may have multiple channels with each other.
+id+:: This is an HTLC counter and starts at +0+ for the first HTLC offered to Bob by Alice and is incremented for each subsequent offered HTLC
+id+:: This is an HTLC counter and starts at +0+ for the first HTLC offered to Bob by Alice and is incremented for each subsequent offered HTLC.
+amount_msat+:: This is the amount (value) of the HTLC in milli-satoshis. In our example this is 50,200,000 milli-satoshis (i.e. 50,200 satoshis).
+amount_msat+:: This is the amount (value) of the HTLC in milli-satoshis. In our example this is 50,200,000 milli-satoshis (i.e., 50,200 satoshis).
+payment_hash+:: This is the payment hash calculated from Dina's invoice. It is +H = RIPEMD160(SHA256(R))+, where R is Dina's secret that is known only by Dina and will be revealed if Dina is paid.
+payment_hash+:: This is the payment hash calculated from Dina's invoice. It is +H = RIPEMD160(SHA256(R))+, where `R` is Dina's secret that is known only by Dina and will be revealed if Dina is paid.
+cltv_expiry+:: This is the expiry time for this HTLC which will be encoded as a timelocked refund in case the HTLC fails to reach Dina in this time.
+cltv_expiry+:: This is the expiry time for this HTLC, which will be encoded as a timelocked refund in case the HTLC fails to reach Dina in this time.
+onion_routing_packet+:: This is an onion-encrypted route that tells Bob where to forward this HTLC next (to Chan). Onion routing is covered in detail in <<onion_routing>>.
@ -87,11 +87,11 @@ Alice sends the `update_add_HTLC` Lightning message to Bob. This message is defi
As a reminder, accounting within the Lightning Network is in units of milli-satoshis (thousandths of a satoshi), whereas Bitcoin accounting is in satoshis. Any amounts in HTLCs are milli-satoshis, which are then rounded to the nearest satoshi in the Bitcoin commitment transactions.
====
==== HTLC in Commitment Transaction
==== HTLC in Commitment Transactions
The received information is enough for Bob to create a new commitment transaction. The new commitment transaction has the same two outputs +to_self+ and +to_remote+ for Alice and Bob's balance, and a *new* output representing the HTLC offered by Alice.
The received information is enough for Bob to create a new commitment transaction. The new commitment transaction has the same two outputs +to_self+ and +to_remote+ for Alice and Bob's balance, and a _new_ output representing the HTLC offered by Alice.
We've already seen the basic structure of an HTLC in <<routing>>. The complete script of an offered HTLC is defined in https://github.com/lightningnetwork/lightning-rfc/blob/master/03-transactions.md#offered-htlc-outputs[BOLT #3-Transactions-Offered HTLC output] and is shown in <<offered_htlc_output_script>> below:
We've already seen the basic structure of an HTLC in <<routing>>. The complete script of an offered HTLC is defined in https://github.com/lightningnetwork/lightning-rfc/blob/master/03-transactions.md#offered-htlc-outputs[BOLT #3-Transactions-Offered HTLC output] and is shown in <<offered_htlc_output_script>>.
[[offered_htlc_output_script]]
@ -116,16 +116,16 @@ OP_ELSE
OP_ENDIF
OP_ENDIF
----
<1> The first clause of the OP_IF conditional is redeemable by Alice with a revocation key. If this commitment is later revoked, Alice will have a revocation key to claim this output in a penalty transaction, taking the whole channel balance.
<2> The second clause is redeemable by the pre-image (payment secret or in our example Dina's secret) if it is revealed. This allows Bob to claim this output if he has the secret from Dina, meaning he has successfully delivered the payment to Dina.
<1> The first clause of the `OP_IF` conditional is redeemable by Alice with a revocation key. If this commitment is later revoked, Alice will have a revocation key to claim this output in a penalty transaction, taking the whole channel balance.
<2> The second clause is redeemable by the pre-image (payment secret, or in our example Dina's secret) if it is revealed. This allows Bob to claim this output if he has the secret from Dina, meaning he has successfully delivered the payment to Dina.
<3> The third and final clause is a refund of the HTLC to Alice, if the HTLC expires without reaching Dina. It is timelocked with the expiration +cltv_expiry+. This ensures that Alice's balance is not "stuck" in an HTLC that can't be routed to Dina.
====
There are three ways to claim this output. Try to read the script and see if you can figure it out (remember, it is a stack-based language so things appear "backwards").
There are three ways to claim this output. Try to read the script and see if you can figure it out (remember, it is a stack-based language so things appear "backward").
==== New Commitment with HTLC Output
Bob now has the necessary information to add this HTLC script as an additional output and create a new commitment transaction. Bob's new commitment will have 50,200 satoshis in the HTLC output. That amount will come from Alice's channel balance, so Alice's new balance will be 19,800 satoshis (70,000 - 50,200 = 19,800). Bob constructs this commitment as a tentative "Commitment #3", shown in <<add_commitment_3b>>, below:
Bob now has the necessary information to add this HTLC script as an additional output and create a new commitment transaction. Bob's new commitment will have 50,200 satoshis in the HTLC output. That amount will come from Alice's channel balance, so Alice's new balance will be 19,800 satoshis (70,000–50,200 = 19,800). Bob constructs this commitment as a tentative "Commitment #3," shown in <<add_commitment_3b>>.
[[add_commitment_3b]]
.Bob's new commitment with an HTLC output
@ -135,7 +135,7 @@ image::images/mtln_0905.png["Bob's new commitment with an HTLC output"]
Shortly after sending the +update_add_htlc+ message, she will commit to the new state of the channel, so that the HTLC can be safely added by Bob. Bob has the HTLC information and has constructed a new commitment but does not yet have this new commitment signed by Alice.
Alice sends +commitment_signed+ to Bob, with the signature for the new commitment and for the HTLC within. We saw the +commitment_signed+ message in <<payment_channels>>, but now we can understand the rest of the fields. As a reminder, it is shown in this code:
Alice sends +commitment_signed+ to Bob, with the signature for the new commitment and for the HTLC within. We saw the +commitment_signed+ message in <<payment_channels>>, but now we can understand the rest of the fields. As a reminder, it is shown in Example 9-3.
[[ops_commitment_signed_message]]
.The commitment_signed message
@ -156,7 +156,7 @@ The fields +num_htlcs+ and +htlc_signature+ now make more sense:
Alice can send these signatures without hesitation: she can always get a refund if the HTLC expires without being routed to Dina.
Now, Bob has a new signed commitment transaction, as shown in <<signed_commitment_3b>> below:
Now, Bob has a new signed commitment transaction, as shown in <<signed_commitment_3b>>.
[[signed_commitment_3b]]
.Bob has a new signed commitment
@ -164,7 +164,7 @@ image::images/mtln_0906.png[Bob has a new signed commitment]
==== Bob Acknowledges New Commitment and Revokes Old One
Now that Bob has a new signed commitment, he needs to acknowledge it and revoke the old commitment. He does so by sending the +revoke_and_ack+ message, as we saw in <<payment_channels>> previously. As a reminder, that message is shown in <<revoke_and_ack_message_2>>, below:
Now that Bob has a new signed commitment, he needs to acknowledge it and revoke the old commitment. He does so by sending the +revoke_and_ack+ message, as we saw in <<payment_channels>> previously. As a reminder, that message is shown in <<revoke_and_ack_message_2>>.
[[revoke_and_ack_message_2]]
.The +revoke_and_ack+ message
@ -178,7 +178,7 @@ Now that Bob has a new signed commitment, he needs to acknowledge it and revoke
Bob sends the +per_commitment_secret+ that allows Alice to construct a revocation key to build a penalty transaction spending Bob's old commitment. Once Bob has sent this, he cannot ever publish "Commitment #2" without risking a penalty transaction and losing all his money. So, the old commitment is effectively revoked.
Bob has effectively moved the channel state forward, as shown in <<revoked_commitment_2b>>:
Bob has effectively moved the channel state forward, as shown in <<revoked_commitment_2b>>.
[[revoked_commitment_2b]]
.Bob has revoked the old commitment
@ -186,11 +186,11 @@ image::images/mtln_0907.png[Bob has revoked the old commitment]
Despite the fact that Bob has a new (signed) commitment transaction and an HTLC output inside he cannot consider his HTLC as being set up successfully.
He first needs to have Alice revoke her old commitment, because otherwise, Alice can roll back her balance to 70,000 satoshis. Bob needs to make sure that Alice also has a commitment transaction containing the HTLC and has revoked the old commitment.
He first needs to have Alice revoke her old commitment because, otherwise, Alice can roll back her balance to 70,000 satoshis. Bob needs to make sure that Alice also has a commitment transaction containing the HTLC and has revoked the old commitment.
That is why, if Bob is not the final recipient of the HTLC funds, he should not "forward" the HTLC yet, by offering an HTLC on the next channel with Chan.
That is why, if Bob is not the final recipient of the HTLC funds, he should not forward the HTLC yet, by offering an HTLC on the next channel with Chan.
Alice has constructed a mirror-image new commitment transaction containing the new HTLC, but it is yet to be signed by Bob. We can see it in <<add_commitment_3a>> below:
Alice has constructed a mirror-image new commitment transaction containing the new HTLC, but it is yet to be signed by Bob. We can see it in <<add_commitment_3a>>.
[[add_commitment_3a]]
.Alice's new commitment with an HTLC output
@ -206,15 +206,15 @@ For completeness sake, let's quickly review the commitment transactions as this
Bob now sends a +commitment_signed+ back to Alice, with his signatures for Alice's new commitment transaction, including the HTLC output she has added.
Now Alice has the signature for the new commitment transaction. The state of the channel is shown in <<signed_commitment_3a>> below:
Now Alice has the signature for the new commitment transaction. The state of the channel is shown in <<signed_commitment_3a>>.
[[signed_commitment_3a]]
.Alice has a new *signed* commitment
image::images/mtln_0909.png[Alice has a new *signed* commitment]
image::images/mtln_0909.png[Alice has a new signed commitment]
Alice can now acknowledge the new commitment by revoking the old one. Alice sends the +revoke_and_ack+ message containing the necessary +per_commitment_point+ that will allow Bob to construct a revocation key and penalty transaction. Thus, Alice revokes her old commitment.
The channel state is shown in <<revoked_commitment_2a>> below:
The channel state is shown in <<revoked_commitment_2a>>.
[[revoked_commitment_2a]]
.Alice has revoked the old commitment
@ -222,31 +222,31 @@ image::images/mtln_0910.png[Alice has revoked the old commitment]
=== Multiple HTLCs
At any point in time, Alice and Bob may have dozens or even hundreds of HTLCs across a single channel. Each HTLC is offered and added to the commitment transaction as an additional output. A commitment transaction therefore always has 2 outputs for the channel partner balances and any number of HTLC outputs, one per HTLC.
At any point in time, Alice and Bob may have dozens or even hundreds of HTLCs across a single channel. Each HTLC is offered and added to the commitment transaction as an additional output. A commitment transaction therefore always has two outputs for the channel partner balances and any number of HTLC outputs, one per HTLC.
As we saw in the +commitment_signed+ message, there is an array for HTLC signatures so that multiple HTLC commitments can be transmitted at the same time.
The current maximum number of HTLCs allowed on a channel is 483 HTLCs to account for the maximum Bitcoin transaction size and ensure that the commitment transactions continue to be valid Bitcoin transactions.
As we will see in the next section, the maximum is only for _pending_ HTLCs, since once an HTLC is fulfilled (or fails due to timeout/error), it is removed from the commitment transaction.
As we will see in the next section, the maximum is only for _pending_ HTLCs because, once an HTLC is fulfilled (or fails due to timeout/error), it is removed from the commitment transaction.
=== HTLC Fulfillment
Now Bob and Alice both have a new commitment transaction with an additional HTLC output and we have achieved a major step towards updating a payment channel.
Now Bob and Alice both have a new commitment transaction with an additional HTLC output and we have achieved a major step toward updating a payment channel.
The new balance of Alice and Bob does not reflect yet that Alice has successfully sent 50,200 satoshis to Bob.
However the HTLCs are now set up in a way that secure settlement in exchange for the proof of payment will be possible.
However, the HTLCs are now set up in a way that secure settlement in exchange for the proof of payment will be possible.
==== HTLC Propagation
Let's assume that Bob continues the chain and sets up an HTLC with Chan for 50,100 satoshis. The process will be exactly the same as we just saw between Alice and Bob. Bob will send +update_add_htlc+ to Chan, then they will exchange +commitment_signed+ and +revoke_and_ack+ messages in two rounds, progressing their channel to the next state.
Let's assume that Bob continues the chain and sets up an HTLC with Chan for 50,100 satoshis. The process will be exactly the same as we just saw between Alice and Bob. Bob will send +update_add_htlc+ to Chan, then they will exchange commitment_signed and +revoke_and_ack+ messages in two rounds, progressing their channel to the next state.
Next, Chan will do the same with Dina: offer a 50,000 satoshi HTLC, commit and revoke etc. However, Dina is the final recipient of the HTLC. Dina is the only one that knows the payment secret (the pre-image of the payment hash). Therefore, Dina can fulfill the HTLC with Chan immediately!
Next, Chan will do the same with Dina: offer a 50,000 satoshi HTLC, commit, and revoke, etc. However, Dina is the final recipient of the HTLC. Dina is the only one that knows the payment secret (the pre-image of the payment hash). Therefore, Dina can fulfill the HTLC with Chan immediately!
==== Dina Fulfills the HTLC with Chan
Dina can settle the HTLC by sending an +update_fulfill_htlc+ message to Chan. The +update_fulfill_htlc+ message is defined in https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md#removing-an-htlc-update_fulfill_htlc-update_fail_htlc-and-update_fail_malformed_htlc[BOLT #2-Peer Protocol-update_fulfill_htlc] and is shown here:
Dina can settle the HTLC by sending an +update_fulfill_htlc+ message to Chan. The +update_fulfill_htlc+ message is defined in https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md#removing-an-htlc-update_fulfill_htlc-update_fail_htlc-and-update_fail_malformed_htlc[BOLT #2-Peer Protocol-update_fulfill_htlc] and is shown here:
[[update_fulfill_htlc_message]]
.The +update_fulfill_htlc+ message
@ -264,7 +264,7 @@ It's a really simple message:
+payment_preimage+:: The secret that proves payment was made and redeems the HTLC. This is the +R+ value that was hashed by Dina to produce the payment hash in the invoice to Alice.
When Chan receives this message, he will immediately check if the +payment_preimage+ (let's call it +R+) produces the payment hash (let's call it +H+) in the HTLC that he offered to Dina. He hashes it like this:
When Chan receives this message, he will immediately check if the payment_preimage (let's call it +R+) produces the payment hash (let's call it +H+) in the HTLC that he offered to Dina. He hashes it like this:
----
H = RIPEMD160( SHA256 (R) )
@ -272,15 +272,15 @@ H = RIPEMD160( SHA256 (R) )
If the result +H+ matches the payment hash in the HTLC, Chan can do a little dance of celebration. This long-awaited secret can be used to redeem the HTLC, and will be passed back along the chain of payment channels all the way to Alice, resolving every HTLC that was part of this payment to Dina.
Let's go back to Alice and Bob's channel and watch them unwind the HTLC. To get there, let's assume Dina sent the +update_fulfill_htlc+ to Chan, Chan sent +update_fulfill_htlc+ to Bob and Bob sent +update_fulfill_htlc+ to Alice. The payment pre-image has propagated all the way back to Alice.
Let's go back to Alice and Bob's channel and watch them unwind the HTLC. To get there, let's assume Dina sent the +update_fulfill_htlc+ to Chan, Chan sent +update_fulfill_htlc+ to Bob, and Bob sent +update_fulfill_htlc+ to Alice. The payment pre-image has propagated all the way back to Alice.
==== Bob Settles the HTLC with Alice
When Bob sends +update_fulfill_htlc+ to Alice, it will contain the same +payment_preimage+ that Dina selected for her invoice. That +payment_preimage+ has traveled backwards along the payment path. At each step, the +channel_id+ will be different and +id+ (HTLC ID) may be different. But the preimage is the same!
When Bob sends +update_fulfill_htlc+ to Alice, it will contain the same payment_preimage that Dina selected for her invoice. That +payment_preimage+ has traveled backward along the payment path. At each step, the +channel_id+ will be different and +id+ (HTLC ID) may be different. But the preimage is the same!
Alice will also validate the +payment_preimage+ received from Bob. She will compare its hash to the HTLC payment hash in the HTLC she offered Bob. She will also find this pre-image matches the hash in Dina's invoice. This is proof that Dina was paid.
The message flow between Alice and Bob is shown in <<htlc_fulfillment_message_flow>> below:
The message flow between Alice and Bob is shown in <<htlc_fulfillment_message_flow>>.
Both Alice and Bob can now remove the HTLC from the commitment transactions and update their channel balances.
They create new commitments (Commitment #4), as shown in <<htlc_fulfillment_commitments_added>> below
They create new commitments (Commitment #4), as shown in <<htlc_fulfillment_commitments_added>>.
[[htlc_fulfillment_commitments_added]]
.The HTLC is removed and balances updated in new commitments
image::images/mtln_0912.png[The HTLC is removed and balances updated in new commitments]
Next, they complete two rounds of commitment and revocation. First, Alice sends +commitment_signed+ to sign Bob's new commitment transaction. Bob responds with +revoke_and_ack+ to revoke his old commitment. Once Bob has moved the state of the channel forward, the commitments look like we see in <<htlc_fulfillment_commitments_bob_commit>> below:
Next, they complete two rounds of commitment and revocation. First, Alice sends +commitment_signed+ to sign Bob's new commitment transaction. Bob responds with +revoke_and_ack+ to revoke his old commitment. Once Bob has moved the state of the channel forward, the commitments look like we see in <<htlc_fulfillment_commitments_bob_commit>>.
[[htlc_fulfillment_commitments_bob_commit]]
.Alice signs Bob's new commitment and Bob revoked the old one
image::images/mtln_0913.png[Alice signs Bob's new commitment and Bob revoked the old one]
Finally, Bob signs Alice's commitment by sending Alice a +commitment_signed+ message. Then Alice acknowledges and revokes her old commitment by sending +revoke_and_ack+ to Bob. The end result is that both Alice and Bob have moved their channel state to Commitment #4, have removed the HTLC and have updated their balances. Their current channel state is represented by the commitment transactions that are shown in <<alice_bob_htlc_fulfilled>> below:
Finally, Bob signs Alice's commitment by sending Alice a +commitment_signed+ message. Then Alice acknowledges and revokes her old commitment by sending +revoke_and_ack+ to Bob. The end result is that both Alice and Bob have moved their channel state to Commitment #4, have removed the HTLC, and have updated their balances. Their current channel state is represented by the commitment transactions that are shown in <<alice_bob_htlc_fulfilled>>.
[[alice_bob_htlc_fulfilled]]
.Alice and Bob settle the HTLC and update balances
@ -310,9 +310,9 @@ image::images/mtln_0914.png[Alice and Bob settle the HTLC and update balances]
If an HTLC cannot be fulfilled, it can be removed from the channel commitment using the same process of commitment and revocation.
Instead of +update_fulfill_htlc+, Bob would send a +update_fail_htlc+ or +update_fail_malformed_htlc+. These two messages are defined in https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md#removing-an-htlc-update_fulfill_htlc-update_fail_htlc-and-update_fail_malformed_htlc[BOLT #2-Peer Protocol-Removing an HTLC].
Instead of +update_fulfill_htlc+, Bob would send a +update_fail_htlc+ or +update_fail_malformed_htlc+. These two messages are defined in https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md#removing-an-htlc-update_fulfill_htlc-update_fail_htlc-and-update_fail_malformed_htlc[BOLT #2-Peer Protocol-Removing an HTLC].
The +update_fail_htlc+ message is shown below:
The +update_fail_htlc+ message is shown in the following:
[[update_fail_htlc_message]]
.The +update_fail_htlc+ message
@ -323,23 +323,23 @@ The +update_fail_htlc+ message is shown below:
[len*byte:reason]
----
It's pretty self-explanatory. The multi-byte +reason+ field is defined in https://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md#failure-messages[BOLT #4-Onion Routing], which we will describe in more detail in <<onion_routing>>.
It's pretty self-explanatory. The multi-byte +reason+ field is defined in https://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md#failure-messages[BOLT #4-Onion Routing], which we will describe in more detail in <<onion_routing>>.
If Alice received a +update_fail_htlc+ from Bob, the process would unfold in much the same way: The two channel partners would remove the HTLC, create updated commitment transactions and go through two rounds of commitment/revocation to move the channel state forward to the next commitment. The only difference: the end balances would revert back to what they were without the HTLC, essentially refunding Alice for the HTLC value.
If Alice received an +update_fail_htlc+ from Bob, the process would unfold in much the same way: the two channel partners would remove the HTLC, create updated commitment transactions, and go through two rounds of commitment/revocation to move the channel state forward to the next commitment. The only difference: the end balances would revert back to what they were without the HTLC, essentially refunding Alice for the HTLC value.
=== Making a Local Payment
At this point, you will easily understand why HTLCs are used for both "remote" and "local" payments. When Alice pays Bob for a coffee, she doesn't just update the channel balance and commit to a new state. Instead, the payment is made with an HTLC, in the same way Alice paid Dina. The fact that there's only one channel "hop" makes no difference. It would work like this:
At this point, you will easily understand why HTLCs are used for both remote and local payments. When Alice pays Bob for a coffee, she doesn't just update the channel balance and commit to a new state. Instead, the payment is made with an HTLC, in the same way Alice paid Dina. The fact that there's only one channel hop makes no difference. It would work like this:
[start=1]
. Alice orders a coffee from Bob's shop page.
. Bob's shop sends an invoice with a payment hash.
. Alice constructs an HTLC from that payment hash.
. Alice offers the HTLC to Bob with +update_add_htlc+.
. Alice and Bob exchange commitments and revocations adding the HTLC to their commitment transactions.
. Bob sends +update_fulfill_htlc+ to Alice with the payment pre-image.
. Alice and Bob exchange commitments and revocations removing the HTLC and updating the channel balances.
* Alice orders a coffee from Bob's shop page.
* Bob's shop sends an invoice with a payment hash.
* Alice constructs an HTLC from that payment hash.
* Alice offers the HTLC to Bob with +update_add_htlc+.
* Alice and Bob exchange commitments and revocations adding the HTLC to their commitment transactions.
* Bob sends +update_fulfill_htlc+ to Alice with the payment pre-image.
* Alice and Bob exchange commitments and revocations removing the HTLC and updating the channel balances.
Whether an HTLC is forwarded across many channels, or just fulfilled in a single channel "hop", the process is exactly the same
Whether an HTLC is forwarded across many channels or just fulfilled in a single channel "hop," the process is exactly the same
=== Conclusion
@ -347,4 +347,4 @@ In this chapter we saw how commitment transactions (from <<payment_channels>>) a
We also saw how a local payment and a multi-hop routed payment are handled identically: using HTLCs.
In the next chapter we will look at the encrypted message routing system called _Onion Routing_
In the next chapter we will look at the encrypted message routing system called _onion routing_
@ -7,7 +7,7 @@ In this chapter we will examine the problem of path finding, understand how unce
=== Path Finding in the Lightning Protocol Suite
Path finding, path selection, multipath payments (MPP), and the payment attempt trial and error loop occupy the majority of the "Payment Layer" at the top of the protocol suite.
Path finding, path selection, multipart payments (MPP), and the payment attempt trial and error loop occupy the majority of the "Payment Layer" at the top of the protocol suite.
These components are highlighted by a double outline in the protocol suite, shown in <<LN_protocol_pathfinding_highlight>>.
@ -147,7 +147,7 @@ We can group these steps into three primary activities:
* Path finding (filtered and ordered by some heuristics)
* Payment attempt(s)
These three activities can be repeated in a _payment round_ if we use the failure returns to update the graph, or if we are doing multipath payments (see <<mpp>>).
These three activities can be repeated in a _payment round_ if we use the failure returns to update the graph, or if we are doing multipart payments (see <<mpp>>).
In the next sections we will look at each of these steps in more detail, as well as more advanced payment strategies.
@ -233,7 +233,7 @@ To quantify the uncertainty of a channel's liquidity, we can apply probability t
* The more channels (hops), the lower the chance of success.
While these may be obvious, they have important implications, especially for the use of multipath payments (see <<mpp>>). The math is not difficult to follow.
While these may be obvious, they have important implications, especially for the use of multipart payments (see <<mpp>>). The math is not difficult to follow.
Let's use probability theory to see how we arrived at these conclusions.
@ -350,15 +350,15 @@ However, this knowledge becomes somewhat "stale" as the other nodes send or rout
Therefore, Selena's node must consider how long to keep this knowledge before assuming that it is stale and no longer useful.
[[mpp]]
=== Multipath Payments (MPP)
=== Multipart Payments (MPP)
_Multipath payments (MPP)_ are a feature that was introduced in the Lightning Network in 2020 and is already very widely available. Multipath payments allow a payment to be split into multiple _parts_ which are sent as HTLCs over several different paths to the intended recipient, preserving the _atomicity_ of the overall payment. In this context, atomicity means that either all the HTLC parts of a payment are eventually fulfilled or the entire payment fails and all the HTLC parts fail. There is no possibility of a partially successful payment.
_Multipart payments (MPP)_ are a feature that was introduced in the Lightning Network in 2020 and is already very widely available. Multipart payments allow a payment to be split into multiple _parts_ which are sent as HTLCs over several different paths to the intended recipient, preserving the _atomicity_ of the overall payment. In this context, atomicity means that either all the HTLC parts of a payment are eventually fulfilled or the entire payment fails and all the HTLC parts fail. There is no possibility of a partially successful payment.
Multipath payments are a significant improvement in the Lightning Network because they make it possible to send amounts that won't "fit" in any single channel by splitting them into smaller amounts for which there is sufficient liquidity. Furthermore, multipath payments have been shown to increase the probability of a successful payment, as compared to a single-path payment.
Multipart payments are a significant improvement in the Lightning Network because they make it possible to send amounts that won't "fit" in any single channel by splitting them into smaller amounts for which there is sufficient liquidity. Furthermore, multipart payments have been shown to increase the probability of a successful payment, as compared to a single-path payment.
[TIP]
====
Now that MPP is available it is best to think of a single-path payment as a subcategory of an MPP. Essentially, a single-path is just a multipath of size one. All payments can be considered as multipath payments unless the size of the payment and liquidity available make it possible to deliver with a single part.
Now that MPP is available it is best to think of a single-path payment as a subcategory of an MPP. Essentially, a single-path is just a multipart of size one. All payments can be considered as multipart payments unless the size of the payment and liquidity available make it possible to deliver with a single part.
====
==== Using MPP
@ -371,7 +371,7 @@ In our example we can see some immediate improvements to our path finding proble
The fundamental question is how to split the payments. More specifically, what are the optimal number of splits and the optimal amounts for each split?
This is an area of ongoing research where novel strategies are emerging. Multipath payments lead to a different algorithmic approach than single-path payments, even though single-path solutions can emerge from a multipath optimization (i.e., a single path may be the optimal solution suggested by a multipath path finding algorithm).
This is an area of ongoing research where novel strategies are emerging. Multipart payments lead to a different algorithmic approach than single-path payments, even though single-path solutions can emerge from a multipart optimization (i.e., a single path may be the optimal solution suggested by a multipart path finding algorithm).
If you recall, we found that the uncertainty of liquidity/balances leads to some (somewhat obvious) conclusions that we can apply in MPP path finding, namely:
@ -395,14 +395,14 @@ To read more about the optimization problem known as minimum-cost flows involved
In our example, Selena's node will attempt to split the 1M satoshi payment into two parts with 600k and 400k satoshi, respectively, and send them on two different paths. This is shown in <<mpp_paths>>.
[[mpp_paths]]
.Sending two parts of a multipath payment
.Sending two parts of a multipart payment
image::images/mtln_1209.png[]
Because the S->X channel can now be utilized, and (luckily for Selena), the B->R channel has sufficient liquidity for 600k satoshis, the two parts are successful along paths that were previously not possible.
==== Trial-And-Error Over Multiple "Rounds"
Multipath payments lead to a somewhat modified trial-and-error loop for payment delivery. Because we are attempting multiple paths in each attempt, we have four possible outcomes:
Multipart payments lead to a somewhat modified trial-and-error loop for payment delivery. Because we are attempting multiple paths in each attempt, we have four possible outcomes:
* All parts succeed, the payment is successful
* Some parts succeed, some fail with errors returned
@ -438,4 +438,4 @@ In this chapter we looked at path finding and payment delivery. We saw how to us
We also examined the uncertainty of channel liquidity (from the perspective of the sender) and the implications that has for path finding. We saw how we can quantify the uncertainty and use probability theory to draw some useful conclusions. We also saw how we can reduce uncertainty by learning from both successful and failed payments.
Finally, we saw how the newly deployed multipath payments feature allows us to split payments into parts, increasing the probability of success even for larger payments.
Finally, we saw how the newly deployed multipart payments feature allows us to split payments into parts, increasing the probability of success even for larger payments.
@ -6,10 +6,10 @@ In just a few years, the Lightning Network has gone from a whitepaper to a rapid
Innovation in the Lightning Network is happening in several different levels:
* At Bitcoin's Core protocol, providing use and demand for new Bitcoin Script opcodes, signing algorithms, and optimizations
* At the Lightning protocol level with new features deployed rapidly network-wide.
* At the Lightning protocol level with new features deployed rapidly network-wide
* At the payment channel level, with new channel constructs and enhancements
* As distinct opt-in features deployed end-to-end by independent implementations that senders and recipients can use if they want.
* With new and exciting Lightning Applications (LApps) build on top of the clients and protocols.
* As distinct opt-in features deployed end-to-end by independent implementations that senders and recipients can use if they want
* With new and exciting Lightning Applications (LApps) build on top of the clients and protocols
Let's look at how these innovations are changing Lightning now and in the near future.
@ -21,7 +21,7 @@ Not only is Lightning advancing rapidly, but it is creating demand for new featu
==== Bitcoin Protocol and Bitcoin Script Innovation
The Bitcoin system is, by necessity, a conservative system that has to preserve compatibility with consensus rules to avoid unplanned forks of the blockchain or partitions of the P2P network. As a result, new features require a lot of coordination and testing before they are implemented in "mainnet", the live production system.
The Bitcoin system is, by necessity, a conservative system that has to preserve compatibility with consensus rules to avoid unplanned forks of the blockchain or partitions of the P2P network. As a result, new features require a lot of coordination and testing before they are implemented in mainnet, the live production system.
Here are some of the current or proposed innovations in Bitcoin that are motivated by use cases in the Lightning Network:
@ -29,17 +29,17 @@ Neutrino:: A lightweight client protocol with improved privacy features over the
Schnorr signatures:: Introduced as part of the _Taproot_ soft fork, Schnorr signatures will enable flexible Point Time-Locked Contracts (PTLC) for channel construction in Lightning. This might in particular make use of revocable signatures instead of revocable transactions.
Taproot:: Also part of the November 2021 soft-fork that introduces Schnorr signatures, Taproot allows complex scripts to appear as single-payer, single-payee payments, and indistinguishable from the most common type of payment on Bitcoin. This will allow Lightning channel cooperative (mutual) closure transactions to appear indistinguishable from simple payments and increase privacy for LN users.
Taproot:: Also part of the November 2021 softfork that introduces Schnorr signatures, Taproot allows complex scripts to appear as single-payer, single-payee payments, and indistinguishable from the most common type of payment on Bitcoin. This will allow Lightning channel cooperative (mutual) closure transactions to appear indistinguishable from simple payments and increase privacy for LN users.
Input re-binding:: Also known by the names SIGHAS_NOINPUT, or SIGHASH_ANYPREVOUT, this planned upgrade to the Bitcoin Script language is primarily motivated by advanced smart contracts such as the eltoo channel protocol.
Input rebinding:: Also known by the names SIGHAS_NOINPUT or SIGHASH_ANYPREVOUT, this planned upgrade to the Bitcoin Script language is primarily motivated by advanced smart contracts such as the eltoo channel protocol.
Covenants:: Currently in the early stages of research, coventants allow transactions to create outputs that constrain future transactions which spend them. This mechanism could increase security for Lightning channels, by making it possible to enforce address whitelisting in commitment transactions.
Covenants:: Currently in the early stages of research, coventants allow transactions to create outputs that constrain future transactions which spend them. This mechanism could increase security for Lightning channels by making it possible to enforce address whitelisting in commitment transactions.
==== Lightning Protocol Innovation
The Lightning P2P protocol is highly extensible and has undergone a lot of change since its inception. The "It's OK to be odd" rule used in feature bits (see <<feature_bits>>) ensure that nodes can negotiate the features they support, enabling multiple independent upgrades to the protocol.
The Lightning P2P protocol is highly extensible and has undergone a lot of change since its inception. The "It's OK to be odd" rule used in feature bits (see <<feature_bits>>) ensures that nodes can negotiate the features they support, enabling multiple independent upgrades to the protocol.
===== TLV extensibility
==== TLV Extensibility
The Type-Length-Value (see <<tlv>>) mechanism for extending the messaging protocol is extremely powerful and has already enabled the introduction of several new capabilities in Lightning while maintaining both forward and backward compatibility.
A prominent example, which is currently being developed and makes use of this, is path blinding and trampoline payments. This allows a recipient to hide itself from the sender, but also allows mobile clients to send payments without the necessity of storing the full channel graph on their devices by using a third party to which they don't need to reveal the final recipient.
@ -48,23 +48,23 @@ A prominent example, which is currently being developed and makes use of this, i
Payment channels are an abstraction that is operated by two channel partners. As long as those two are willing to run new code, they can implement a variety of channel mechanisms simultaneously. In fact, recent research suggests that channels could even be upgraded to a new mechanism dynamically, without closing the old channel and opening a new channel type.
Eltoo:: A proposed channel mechanism that uses input-rebinding to significantly simplify the operation of payment channels and remove the need for the penalty mechanism. It needs a new Bitcoin signature type before it can be implemented
eltoo:: A proposed channel mechanism that uses input-rebinding to significantly simplify the operation of payment channels and remove the need for the penalty mechanism. It needs a new Bitcoin signature type before it can be implemented
==== Opt-In End-to-End Features
Point Time-Locked Contracts (PTLCs):: A different approach to HTLCs, PTLCs can increase privacy, reduce information leaked to intermediary nodes and operate more efficiently than HTLC-based channels.
Point Time-Locked Contracts (PTLCs):: A different approach to HTLCs, PTLCs can increase privacy, reduce information leaked to intermediary nodes, and operate more efficiently than HTLC-based channels.
Large channels:: Large or "Wumbo" channels were introduced in a dynamic way to the network without requiring coordination. Channels that support large payments are advertized as part of the channel announcement messages and can be used in an opt-in manner.
Large channels:: Large or _Wumbo_ channels were introduced in a dynamic way to the network without requiring coordination. Channels that support large payments are advertized as part of the channel announcement messages and can be used in an opt-in manner.
Multi-Part Payments (MPP):: MPP was also introduced in an opt-in manner, but even better only requires the sender and recipient of a payment to be able to do MPP. The rest of the network simply routes HTLCs as if they are single-part payments.
Multipart payments (MPP):: MPP was also introduced in an opt-in manner, but even better only requires the sender and recipient of a payment to be able to do MPP. The rest of the network simply routes HTLCs as if they are single-part payments.
JIT-Routing:: An optional method that can be used by routing nodes to increase their reliability and to protect themselves from being spammed.
Keysend:: An upgrade introduced independently by Lightning client implementations, it allows the sender to send money in an "unsolicited" and asynchronous way without requiring an invoice first.
HODL invoices:: Payments where the final HTLC is not collected, committing the sender to the payment, but allowing the recipient to delay collection until some other condition is satisfied, or cancel the invoice without collection. This was also implemented independently by different Lightning clients and can be used opt-in.
HODL invoicesfootnote:[The word _HODL_ comes from an excited misspelling of the word "HOLD" shouted in a forum to encourage people not to sell bitcoin in a panic.]:: Payments where the final HTLC is not collected, committing the sender to the payment, but allowing the recipient to delay collection until some other condition is satisfied, or cancel the invoice without collection. This was also implemented independently by different Lightning clients and can be used in an opt-in manner.
Onion routed message services:: The onion routing mechanism, and the underlying public key databse of nodes can be used to send data that is unrelated to payments, such as text messages or forum posts. The use of Lightning to enable paid messaging as a solution to spam posts and sybil attacks (spam) is another innovation that was implemented independently of the core protocol.
Onion routed message services:: The onion routing mechanism and the underlying public key databse of nodes can be used to send data that is unrelated to payments, such as text messages or forum posts. The use of Lightning to enable paid messaging as a solution to spam posts and Sybil attacks (spam) is another innovation that was implemented independently of the core protocol.
Offers:: Currently proposed as BOLT #12 but already implemented by some nodes, this is a communication protocol to request (recurring) invoices from remote nodes via Onion messages.
@ -73,8 +73,8 @@ Offers:: Currently proposed as BOLT #12 but already implemented by some nodes, t
While still in their infancy, we are already seeing the emergence of interesting Lightning Applications. Broadly defined as an application that uses the Lightning Protocol or a Lightning client as a component, LApps are the application layer of Lightning.
A prominent example is LNURL, which provides a similar functionality as BOLT #12 Offers, but just over http and Lightning addresses. It works on top of Offers to provide users with an email-style address to which others can send funds while the software in the background requests an invoice against the LNURL endpoint of the node.
Further LApps are being built for simple games, messaging applications, micro-services, payable-APIs, paid dispensers (eg. fuel pumps), derivative trading systems, and much more.
Further LApps are being built for simple games, messaging applications, microservices, payable APIs, paid dispensers (e.g., fuel pumps), derivative trading systems, and much more.
=== Ready, Set, Go!
The future is looking bright. The Lightning Network is taking Bitcoin to new unexplored markets and applications. Equipped with the knowledge in this book, you can explore this new frontier, or maybe even join as a pioneer and forge a new path.
The future is looking bright. The Lightning Network is taking Bitcoin to new unexplored markets and applications. Equipped with the knowledge in this book, you can explore this new frontier or maybe even join as a pioneer and forge a new path.
The Lightning Network is capable of running above multiple blockchains, but is primarily anchored on Bitcoin. To understand LN, you need a fundamental understanding of Bitcoin and its building blocks.
The Lightning Network is capable of running above multiple blockchains, but is primarily anchored on Bitcoin. To understand the Lightning Network, you need a fundamental understanding of Bitcoin and its building blocks.
There are many good resources that you can use to learn more about Bitcoin, including the "companion" book _Mastering Bitcoin 2nd Edition_, written by Andreas M. Antonopoulos, which you can find on GitHub under an open source license. However, you do not need to read a whole other book to be ready for this one!
There are many good resources that you can use to learn more about Bitcoin, including the companion book _Mastering Bitcoin_, 2nd Edition, written by Andreas M. Antonopoulos, which you can find on GitHub under https://github.com/bitcoinbook/bitcoinbook[an open source license]. However, you do not need to read a whole other book to be ready for this one!
In this chapter, we've collected the most important concepts you need to know about Bitcoin and explained them in the context of the Lightning Network. This way you can learn exactly what you need to know in order to grasp the Lightning Network without any distractions.
In this chapter, we've collected the most important concepts you need to know about Bitcoin and explained them in the context of the Lightning Network. This way you can learn exactly what you need to know to grasp the Lightning Network without any distractions.
This chapter covers several important concepts from Bitcoin, including:
@ -15,7 +15,7 @@ This chapter covers several important concepts from Bitcoin, including:
* Bitcoin transactions and their structure
* Bitcoin transaction chaining
* Transaction outpoints
* Bitcoin Script - locking and unlocking scripts
* Bitcoin Script: locking and unlocking scripts
* Basic locking scripts
* Complex and conditional locking scripts
* Timelocks
@ -23,17 +23,17 @@ This chapter covers several important concepts from Bitcoin, including:
=== Keys and Digital Signatures
You may have heard that bitcoin is based on _cryptography_, which is a branch of mathematics used extensively in computer security. Cryptography can also be used to prove knowledge of a secret without revealing that secret (digital signature), or prove the authenticity of data (digital fingerprint). These types of cryptographic proofs are the mathematical tools critical to bitcoin and used extensively in bitcoin applications.
You may have heard that bitcoin is based on _cryptography_, which is a branch of mathematics used extensively in computer security. Cryptography can also be used to prove knowledge of a secret without revealing that secret (digital signature), or prove the authenticity of data (digital fingerprint). These types of cryptographic proofs are the mathematical tools critical to Bitcoin and used extensively in Bitcoin applications.
Ownership of bitcoin is established through _digital keys_, _bitcoin addresses_, and _digital signatures_. The digital keys are not actually stored in the network, but are instead created and stored by users in a file, or simple database, called a _wallet_. The digital keys in a user's wallet are completely independent of the bitcoin protocol and can be generated and managed by the user's wallet software without reference to the blockchain or access to the internet.
Ownership of bitcoin is established through _digital keys_, _bitcoin addresses_, and _digital signatures_. The digital keys are not actually stored in the network, but are instead created and stored by users in a file, or simple database, called a _wallet_. The digital keys in a user's wallet are completely independent of the Bitcoin Protocol and can be generated and managed by the user's wallet software without reference to the blockchain or access to the internet.
Most bitcoin transactions require a valid digital signature to be included in the blockchain, which can only be generated with a secret key; therefore, anyone with a copy of that key has control of the bitcoin. The digital signature used to spend funds is also referred to as a _witness_, a term used in cryptography. The witness data in a bitcoin transaction testifies to the true ownership of the funds being spent. Keys come in pairs consisting of a private (secret) key and a public key. Think of the public key as similar to a bank account number and the private key as similar to the secret PIN.
Most Bitcoin transactions require a valid digital signature to be included in the blockchain, which can only be generated with a secret key; therefore, anyone with a copy of that key has control of the bitcoin. The digital signature used to spend funds is also referred to as a _witness_, a term used in cryptography. The witness data in a bitcoin transaction testifies to the true ownership of the funds being spent. Keys come in pairs consisting of a private (secret) key and a public key. Think of the public key as similar to a bank account number and the private key as similar to the secret PIN.
==== Private and Public Keys
A private key is simply a number, picked at random. In practice, and to make managing many keys easy, most bitcoin wallets generate a sequence of private keys from a single random _seed_, using a deterministic derivation algorithm. Simply put, a single random number is used to produce a repeatable sequence of seemingly random numbers that are used as private keys. This allows users to only backup the seed and be able to _derive_ all the keys they need from that seed.
A private key is simply a number, picked at random. In practice, and to make managing many keys easy, most Bitcoin wallets generate a sequence of private keys from a single random _seed_ using a deterministic derivation algorithm. Simply put, a single random number is used to produce a repeatable sequence of seemingly random numbers that are used as private keys. This allows users to only backup the seed and be able to _derive_ all the keys they need from that seed.
Bitcoin, like many other cryptocurrencies and blockchains, uses _elliptic curves_ for security. In Bitcoin, elliptic curve multiplication on the _secp256k1_ elliptic curve is used as a _one-way function_. Simply put, the nature of elliptic curve math makes it trivial to calculate the scalar multiplication of a point but impossible to calculate the inverse ("division", or "discrete logarithm").
Bitcoin, like many other cryptocurrencies and blockchains, uses _elliptic curves_ for security. In Bitcoin, elliptic curve multiplication on the _secp256k1_ elliptic curve is used as a _one-way function_. Simply put, the nature of elliptic curve math makes it trivial to calculate the scalar multiplication of a point but impossible to calculate the inverse (division, or discrete logarithm).
Each private key has a corresponding _public key_, which is calculated from the private key, using scalar multiplication on the elliptic curve. In simple terms, with a private key +k+, we can multiply it with a constant +G+ to produce a public key +K+:
@ -47,14 +47,14 @@ It is impossible to reverse this calculation. Given a public key +K+, one cannot
Another important tool used extensively in Bitcoin, and in the Lightning Network, are _cryptographic hash functions_ and specifically the +SHA-256+ hash function.
A hash function, also known as a _digest function_, is a function that takes arbitrary length data and transforms it into a fixed length result, called the _hash_, _digest_, or _fingerprint_. Importantly, hash functions are _one-way_ functions meaning that you can't reverse them and calculate the input data from the fingerprint.
A hash function, also known as a _digest function_, is a function that takes arbitrary length data and transforms it into a fixed length result, called the _hash_, _digest_, or _fingerprint_ (see <<SHA256>>). Importantly, hash functions are _one-way_ functions, meaning that you can't reverse them and calculate the input data from the fingerprint.
For example, if we use a command-line terminal to feed the text "Mastering the Lightning Network" into the SHA256 function it will produce a fingerprint as follows:
For example, if we use a command-line terminal to feed the text "Mastering the Lightning Network" into the SHA256 function, it will produce a fingerprint as follows:
----
$ echo -n "Mastering the Lightning Network" | shasum -a 256
The input used to calculate a hash is also called a _pre-image_.
The input used to calculate a hash is also called a _preimage_.
====
The length of the input can be much bigger of course. Let's try the same thing with the PDF file of the Bitcoin whitepaper from Satoshi Nakamoto:
The length of the input can be much bigger, of course. Let's try the same thing with the https://bitcoin.org/bitcoin.pdf[PDF file of the Bitcoin whitepaper] from Satoshi Nakamoto:
----
$ wget http://bitcoin.org/bitcoin.pdf
@ -79,7 +79,7 @@ While it takes longer than a single sentence, the SHA256 function processes the
Now at this point you might be wondering how it is possible for a function that digests data of unlimited size to produce a unique fingerprint that is a fixed-size number?
In theory, since there is an infinite number of possible pre-images (inputs) and only a finite number of fingerprints, there must be many pre-images that produce the same 256-bit fingerprint. When two pre-images produce the same hash, this is known as a _collision_.
In theory, since there is an infinite number of possible preimages (inputs) and only a finite number of fingerprints, there must be many preimages that produce the same 256-bit fingerprint. When two preimages produce the same hash, this is known as a _collision_.
In practice, a 256-bit number is so large that you will never find a collision on purpose. Cryptographic hash functions work on the basis that a search for a collision is a brute-force effort that takes so much energy and time that it is not practically possible.
@ -87,7 +87,7 @@ Cryptographic hash functions are broadly used in a variety of applications becau
Deterministic:: The same input always produces the same hash.
Irreversible:: It is not possible to compute the pre-image of a hash.
Irreversible:: It is not possible to compute the preimage of a hash.
Collision-Proof:: It is computationally infeasible to find two messages that have the same hash.
@ -99,56 +99,62 @@ Using these features of cryptographic hashes, we can build some interesting appl
Fingerprints:: A hash can be used to fingerprint a file or message so that it can be uniquely identified. Hashes can be used as universal identifiers of any data set.
Integrity Proof:: A fingerprint of a file or message demonstrates its integrity, as the file or message cannot be tampered with or modified in any way without changing the fingerprint. This is often used to ensure software has not been tampered with before installing it on your computer.
Integrity proof:: A fingerprint of a file or message demonstrates its integrity because the file or message cannot be tampered with or modified in any way without changing the fingerprint. This is often used to ensure software has not been tampered with before installing it on your computer.
Commitment/Non-repudiation:: You can commit to a specific pre-image (e.g. a number or message) without revealing it, by publishing its hash. Later, you can reveal the secret and everyone can verify that it is the same thing you committed to earlier because it produces the published hash.
Commitment/nonrepudiation:: You can commit to a specific preimage (e.g., a number or message) without revealing it by publishing its hash. Later, you can reveal the secret, and everyone can verify that it is the same thing you committed to earlier because it produces the published hash.
Proof-of-Work/Hash Grinding:: You can use a hash to prove you have done computational work, by showing a non-random pattern in the hash which can only be produced by repeated guesses at a pre-image. For example, the hash of a Bitcoin block header starts with a lot of zero bits. The only way to produce it is by changing a part of the header and hashing it trillions of times until it produces that pattern by chance.
Proof-of-work/hash grinding:: You can use a hash to prove you have done computational work by showing a nonrandom pattern in the hash which can only be produced by repeated guesses at a preimage. For example, the hash of a Bitcoin block header starts with a lot of zero bits. The only way to produce it is by changing a part of the header and hashing it trillions of times until it produces that pattern by chance.
Atomicity:: You can make a secret pre-image a pre-requisite of spending funds in several linked transactions. If any one of the parties reveals the pre-image in order to spend one of the transactions, all the other parties can now spend their transactions too. All or none become spendable, achieving atomicity across several transactions.
Atomicity:: You can make a secret preimage a prerequisite of spending funds in several linked transactions. If any one of the parties reveals the preimage in order to spend one of the transactions, all the other parties can now spend their transactions too. All or none become spendable, achieving atomicity across several transactions.
==== Digital Signatures
The private key is used to create signatures that are required to spend bitcoin by proving ownership of funds used in a transaction.
A digital signature is a number that is calculated from the application of the private key to a specific message.
A _digital signature_ is a number that is calculated from the application of the private key to a specific message.
Given a message m and a private key k, a signature function F_sig_ can produce a signature S:
Given a message _m_ and a private key _k_, a signature function __F~sign~__ can produce a signature _S_:
latexmath:[$ S = F{sign}(m, k) $]
[latexmath]
++++
$ S = F_{sign}(m, k) $
++++
This signature S can be independently verified by anyone who has the public key K (corresponding to private key k), and the message:
This signature _S_ can be independently verified by anyone who has the public key _K_ (corresponding to private key _k_), and the message:
latexmath:[$ F{verify}(m, K, S) $]
[latexmath]
++++
$ F_{verify}(m, K, S) $
++++
If F_verify_ returns a true result, then the verifier can confirm that the message m was signed by someone who had access to the private key k. Importantly, the digital signature proves the possession of the private key k at the time of signing, without revealing k.
If __F~verify~__ returns a true result, then the verifier can confirm that the message _m_ was signed by someone who had access to the private key _k_. Importantly, the digital signature proves the possession of the private key _k_ at the time of signing, without revealing _k_.
Digital signatures use a cryptographic hash algorithm. The signature is applied to a hash of the message, so that the message m is "summarized" to a fixed-length hash H(m) that serves as a fingerprint.
Digital signatures use a cryptographic hash algorithm. The signature is applied to a hash of the message, so that the message _m_ is "summarized" to a fixed-length hash _H_(_m_) that serves as a fingerprint.
By applying the digital signature on the hash of a transaction, the signature not only proves the authorization, but also "locks" the transaction data ensuring its integrity. A signed transaction cannot be modified because any change would result in a different hash and invalidate the signature.
By applying the digital signature on the hash of a transaction, the signature not only proves the authorization, but also "locks" the transaction data, ensuring its integrity. A signed transaction cannot be modified because any change would result in a different hash and invalidate the signature.
==== Signature Types
Signatures are not always applied to the entire transaction. To provide signing flexibility, a Bitcoin digital signature contains a prefix called the signature hash type, which specifies which part of the transaction data is included in the hash. This allows the signature to commit or "lock" all, or only some of, the data in the transaction. The most common signature hash type is +SIGHASH_ALL+ which locks everything in the transaction, by including all the transaction data in the hash that is signed. By comparison, +SIGHASH_SINGLE+ locks all the transaction inputs, but only one output (more about inputs and outputs in the next section). Different signature hash types can be combined to produce six different "patterns" of transaction data that is locked by the signature.
Signatures are not always applied to the entire transaction. To provide signing flexibility, a Bitcoin digital signature contains a prefix called the signature hash type, which specifies which part of the transaction data is included in the hash. This allows the signature to commit or "lock" all, or only some of, the data in the transaction. The most common signature hash type is +SIGHASH_ALL+ which locks everything in the transaction, by including all the transaction data in the hash that is signed. By comparison, +SIGHASH_SINGLE+ locks all the transaction inputs, but only one output (more about inputs and outputs in the next section). Different signature hash types can be combined to produce six different "patterns" of transaction data that are locked by the signature.
More information about signature hash types can be found in https://github.com/bitcoinbook/bitcoinbook/blob/develop/ch06.asciidoc#sighash_types[_Mastering Bitcoin Second Edition - Chapter 6 - Signature Hash Types_]
More information about signature hash types can be found in https://github.com/bitcoinbook/bitcoinbook/blob/develop/ch06.asciidoc#sighash_types[the section "Signature Hash Types" in Chapter 6 of _Mastering Bitcoin_, Second Edition].
=== Bitcoin Transactions
Transactions are data structures that encode the transfer of value between participants in the bitcoin system.
_Transactions_ are data structures that encode the transfer of value between participants in the bitcoin system.
[[utxo]]
==== Inputs and Outputs
The fundamental building block of a bitcoin transaction is a transaction output. Transaction outputs are indivisible chunks of bitcoin currency, recorded on the blockchain, and recognized as valid by the entire network. A transaction spends "inputs" and creates "outputs". Transaction inputs are simply references to outputs of previously recorded transactions. This way, each transaction spends the outputs of previous transactions and creates new outputs.
The fundamental building block of a bitcoin transaction is a transaction output. _Transaction outputs_ are indivisible chunks of bitcoin currency, recorded on the blockchain, and recognized as valid by the entire network. A transaction spends inputs and creates outputs. Transaction _inputs_ are simply references to outputs of previously recorded transactions. This way, each transaction spends the outputs of previous transactions and creates new outputs (see <<transaction_structure>>).
[[transaction_structure]]
.A transaction transfers value from inputs to outputs
image::images/mtln_aa02.png["transaction inputs and outputs"]
Bitcoin full nodes track all available and spendable outputs, known as _unspent transaction outputs_, or UTXOs. The collection of all UTXOs is known as the UTXO set and currently numbers in the millions of UTXOs. The UTXO set grows as new UTXOs are created and shrinks when UTXOs are consumed. Every transaction represents a change (state transition) in the UTXO set, by consuming one or more UTXOs as _transaction inputs_ and creating one or more UTXOs as its _transaction outputs_.
Bitcoin full nodes track all available and spendable outputs, known as _unspent transaction outputs_ (UTXOs). The collection of all UTXOs is known as the UTXO set, which currently numbers in the millions of UTXOs. The UTXO set grows as new UTXOs are created and shrinks when UTXOs are consumed. Every transaction represents a change (state transition) in the UTXO set, by consuming one or more UTXOs as _transaction inputs_ and creating one or more UTXOs as its _transaction outputs_.
For example, let's assume that a user Alice has a 100,000 satoshi UTXO that she can spend. Alice can pay Bob 100,000 satoshi, by constructing a transaction with one input (consuming her existing 100,000 satoshi input) and one output that "pays" Bob 100,000 satoshi. Now Bob has a 100,000 satoshi UTXO that he can spend, creating a new transaction that consumes this new UTXO and spends it to another UTXO as a payment to another user, and so on.
For example, let's assume that a user Alice has a 100,000 satoshi UTXO that she can spend. Alice can pay Bob 100,000 satoshi by constructing a transaction with one input (consuming her existing 100,000 satoshi input) and one output that "pays" Bob 100,000 satoshi. Now Bob has a 100,000 satoshi UTXO that he can spend, creating a new transaction that consumes this new UTXO and spends it to another UTXO as a payment to another user, and so on (see <<alice_100ksat_to_bob>>).
[[alice_100ksat_to_bob]]
.Alice pays 100,000 satoshis to Bob
@ -156,7 +162,7 @@ image::images/mtln_aa03.png["Alice pays 100,000 satoshis to Bob"]
A transaction output can have an arbitrary (integer) value denominated in satoshis. Just as dollars can be divided down to two decimal places as cents, bitcoin can be divided down to eight decimal places as satoshis. Although an output can have any arbitrary value, once created it is indivisible. This is an important characteristic of outputs that needs to be emphasized: outputs are discrete and indivisible units of value, denominated in integer satoshis. An unspent output can only be consumed in its entirety by a transaction.
So what if Alice wants to pay Bob 50,000 satoshi, but only has an indivisible 100,000 satoshi UTXO? Alice will need to create a transaction that consumes (as its input) the 100,000 satoshi UTXO and has two outputs: one paying 50,000 satoshi to Bob and one paying 50,000 satoshi *back* to Alice as "change".
So what if Alice wants to pay Bob 50,000 satoshi, but only has an indivisible 100,000 satoshi UTXO? Alice will need to create a transaction that consumes (as its input) the 100,000 satoshi UTXO and has two outputs: one paying 50,000 satoshi to Bob and one paying 50,000 satoshi _back_ to Alice as "change" (see <<alice_50ksat_to_bob_change>>).
[[alice_50ksat_to_bob_change]]
.Alice pays 50k sat to Bob and 50k sat to herself as change
@ -164,39 +170,39 @@ image::images/mtln_aa04.png["Alice pays 50,000 satoshis to Bob and 50,000 satosh
[TIP]
====
There's nothing "special" about a change output or any way to distinguish it from any other output. It doesn't have to be the last output. There could be more than one change output, or no change outputs. Only the creator of the transaction knows which outputs are to others and which outputs are to addresses they own and therefore "change".
There's nothing special about a change output or any way to distinguish it from any other output. It doesn't have to be the last output. There could be more than one change output, or no change outputs. Only the creator of the transaction knows which outputs are to others and which outputs are to addresses they own and therefore "change."
====
Similarly, if Alice wants to pay Bob 85,000 satoshi but has two 50,000 satoshi UTXOs available, she has to create a transaction with two inputs (consuming both her 50,000 satoshi UTXOs) and two outputs, paying Bob 85,000 and sending 15,000 satoshi back to herself as change.
Similarly, if Alice wants to pay Bob 85,000 satoshi but has two 50,000 satoshi UTXOs available, she has to create a transaction with two inputs (consuming both her 50,000 satoshi UTXOs) and two outputs, paying Bob 85,000 and sending 15,000 satoshi back to herself as change (see <<tx_twoin_twoout>>).
[[tx_twoin_twoout]]
.Alice uses two 50k inputs to pay 85k sat to Bob and 50k sat to herself as change
image::images/mtln_aa05.png["Alice uses two 50k inputs to pay 85k sat to Bob and 50k sat to herself as change"]
.Alice uses two 50k inputs to pay 85k sat to Bob and 15k sat to herself as change
image::images/mtln_aa05.png["Alice uses two 50k inputs to pay 85k sat to Bob and 15k sat to herself as change"]
The illustrations and examples above show how a Bitcoin transaction combines (spends) one or more inputs and creates one or more outputs. A transaction can have hundreds or even thousands of inputs and outputs.
The preceding illustrations and examples show how a Bitcoin transaction combines (spends) one or more inputs and creates one or more outputs. A transaction can have hundreds or even thousands of inputs and outputs.
[TIP]
====
While the transactions created by the Lightning Network have multiple outputs they do not have "change" per se, because the entire available balance of a channel is split between the two channel partners.
While the transactions created by the Lightning Network have multiple outputs, they do not have "change" per se, because the entire available balance of a channel is split between the two channel partners.
====
==== Transaction Chains
Every output can be spent, as an input in a subsequent transaction. So for example, if Bob decided to spend 10,000 satoshi in a transaction paying Chan, and Chan spend 4,000 satoshi to pay Dina:
Every output can be spent as an input in a subsequent transaction. So, for example, if Bob decided to spend 10,000 satoshi in a transaction paying Chan, and Chan spent 4,000 satoshi to pay Dina, it would play out as shown in <<tx_chain>>.
[[tx_chain]]
.Alice pays Bob who pays Chan who pays Dina
image::images/mtln_aa06.png["Alice pays Bob who pays Chan who pays Dina"]
An output is considered "spent" if it is referenced as an input in another transaction that is recorded on the blockchain. An output is considered "unspent" (and available for spending) if no recorded transaction references it.
An output is considered _spent_ if it is referenced as an input in another transaction that is recorded on the blockchain. An output is considered _unspent_ (and available for spending) if no recorded transaction references it.
The only type of transaction that doesn't have "inputs" is a special transaction created by Bitcoin miners called the _coinbase transaction_. The coinbase transaction has only outputs and no inputs because it creates new bitcoin from mining. Every other transaction spends one or more previously recorded outputs as its inputs.
The only type of transaction that doesn't have inputs is a special transaction created by Bitcoin miners called the _coinbase transaction_. The coinbase transaction has only outputs and no inputs because it creates new bitcoin from mining. Every other transaction spends one or more previously recorded outputs as its inputs.
Since transactions are chained, if you pick a transaction at random, you can follow any one of its inputs backwards to the previous transaction that created it. If you keep doing that you will eventually reach a coinbase transaction where the bitcoin was first mined.
Since transactions are chained, if you pick a transaction at random, you can follow any one of its inputs backward to the previous transaction that created it. If you keep doing that, you will eventually reach a coinbase transaction where the bitcoin was first mined.
==== TxID: Transaction Identifiers
Every transaction in the Bitcoin system is identified by a unique identifier (assuming the existence of BIP-0030), called the _transaction ID_ or _TxID_ for short. To produce a unique identifier, we use the SHA-256 cryptographic hash function to produce a hash of the transaction's data. This "fingerprint" serves as a universal identifier. A transaction can be referenced by its transaction ID and once a transaction is recorded on the Bitcoin blockchain, every node in the Bitcoin network knows that this transaction is valid.
Every transaction in the Bitcoin system is identified by a unique identifier (assuming the existence of BIP-0030), called the _transaction ID_ or _TxID_ for short. To produce a unique identifier, we use the SHA-256 cryptographic hash function to produce a hash of the transaction's data. This "fingerprint" serves as a universal identifier. A transaction can be referenced by its transaction ID, and once a transaction is recorded on the Bitcoin blockchain, every node in the Bitcoin network knows that this transaction is valid.
For example, a transaction ID might look like this:
@ -205,30 +211,37 @@ For example, a transaction ID might look like this:
As every transaction has a unique ID, we can also identify a transaction output within that transaction uniquely by reference to the TxID and the output index number. The first output in a transaction is output index 0, the second output is output index 1 and so on. An output identifier is commonly known as an _outpoint_.
Because every transaction has a unique ID, we can also identify a transaction output within that transaction uniquely by reference to the TxID and the output index number. The first output in a transaction is output index 0, the second output is output index 1, and so on. An output identifier is commonly known as an _outpoint_.
By convention we write an outpoint as the TxID, a colon and the output index number:
By convention we write an outpoint as the TxID, a colon, and the output index number:
.A outpoint: identifying an output by TxID and index number
Output identifiers (outpoints) are the mechanism that links transactions together in a chain. Every transaction input is a reference to a specific output of a previous transaction. That reference is an outpoint: a TxID and output index number. So a transaction "spends" a specific output (by index number) from a specific transaction (by TxID) to create new outputs that themselves can be spent by reference to the outpoint.
Output identifiers (outpoints) are the mechanisms that link transactions together in a chain. Every transaction input is a reference to a specific output of a previous transaction. That reference is an outpoint: a TxID and output index number. So a transaction "spends" a specific output (by index number) from a specific transaction (by TxID) to create new outputs that themselves can be spent by reference to the outpoint.
Here's the chain of transactions from Alice to Bob to Chan to Dina, this time with outpoints in each of the inputs:
<<tx_chain_vout>> presents the chain of transactions from Alice to Bob to Chan to Dina, this time with outpoints in each of the inputs.
[[tx_chain_vout]]
.Transaction inputs refer to outpoints forming a chain
@ -236,19 +249,19 @@ image::images/mtln_aa07.png["Transaction inputs refer to outpoints forming a cha
The input in Bob's transaction references Alice's transaction (by TxID) and the 0 indexed output.
The input in Chan's transaction references Bob's transaction's TxID and the 1st indexed output, because the payment to Chan is output #1. In Bob's payment to Chan, Bob's change is output #0.footnote:[Recall that change doesn't have to be the last output in a transaction and is in fact indistinguishable from other outputs]
The input in Chan's transaction references Bob's transaction's TxID and the first indexed output, because the payment to Chan is output #1. In Bob's payment to Chan, Bob's change is output #0.footnote:[Recall that change doesn't have to be the last output in a transaction and is in fact indistinguishable from other outputs.]
Now, if we look at Alice's payment to Bob, we can see that Alice is spending an outpoint that was the 3rd (output index #2) output in a transaction whose ID is 6a5f1b3... We don't see that referenced transaction in the diagram, but we can deduce these details from the outpoint.
Now, if we look at Alice's payment to Bob, we can see that Alice is spending an outpoint that was the third (output index #2) output in a transaction whose ID is 6a5f1b3[...]. We don't see that referenced transaction in the diagram, but we can deduce these details from the outpoint.
=== Bitcoin Script
The final element of Bitcoin that is needed to complete our understanding is the scripting language that controls access to outpoints. So far, we've simplified the description by saying "Alice signs the transaction to pay Bob". Behind the scenes, however, there is some hidden complexity that makes it possible to implement more complex spending conditions. The simplest and most common spending condition is "present a signature matching the following public key". A spending condition like this is recorded in each output as _locking script_ written in a scripting language called _Bitcoin Script_.
The final element of Bitcoin that is needed to complete our understanding is the scripting language that controls access to outpoints. So far, we've simplified the description by saying "Alice signs the transaction to pay Bob." Behind the scenes, however, there is some hidden complexity that makes it possible to implement more complex spending conditions. The simplest and most common spending condition is "present a signature matching the following public key." A spending condition like this is recorded in each output as _locking script_ written in a scripting language called _Bitcoin Script_.
Bitcoin Script is an extremely simple stack-based scripting language. It does not contain loops or recursion and therefore is Turing Incomplete (meaning it cannot express arbitrary complexity and has predictable execution). Those familiar with the (now ancient) programming language FORTH will recognize the syntax and style.
Bitcoin Script is an extremely simple stack-based scripting language. It does not contain loops or recursion and therefore is _Turing incomplete_ (meaning it cannot express arbitrary complexity and has predictable execution). Those familiar with the (now ancient) programming language FORTH will recognize the syntax and style.
==== Running Bitcoin Script
In simple terms, the Bitcoin system evaluates Bitcoin Script by running the script on a stack and if the final result is +TRUE+, considers the spending condition satisfied and the transaction "valid".
In simple terms, the Bitcoin system evaluates Bitcoin Script by running the script on a stack; if the final result is +TRUE+, it considers the spending condition satisfied and the transaction valid.
Let's look at a very simple example of Bitcoin Script, which adds the numbers 2 and 3 and then compares the result to the number 5:
@ -256,27 +269,27 @@ Let's look at a very simple example of Bitcoin Script, which adds the numbers 2
2 3 ADD 5 EQUAL
----
In the diagram below, we see how this script is executed (from left to right):
In <<figa08>>, we see how this script is executed (from left to right).
[[figa08]]
.Caption here
.Example of Bitcoin Script execution
image::images/mtln_aa08.png["Example of Bitcoin Script execution"]
==== Locking and Unlocking Scripts
Bitcoin Script is made up of two parts:
_Locking scripts_ are embedded in transaction outputs, setting the conditions that must be fulfilled to spend that output. For example, Alice's wallet adds a locking script to the output paying Bob that sets the condition that Bob's signature is required to spend it.
Locking scripts:: These are embedded in transaction outputs, setting the conditions that must be fulfilled to spend that output. For example, Alice's wallet adds a locking script to the output paying Bob that sets the condition that Bob's signature is required to spend it.
_Unlocking scripts_ are embedded in transaction inputs, fulfilling the conditions set by the referenced output's locking script. For example, Bob can unlock the output above by providing an unlocking script containing a digital signature.
Unlocking scripts:: These are embedded in transaction inputs, fulfilling the conditions set by the referenced output's locking script. For example, Bob can unlock the preceding output by providing an unlocking script containing a digital signature.
Using a simplified model, for validation, the unlocking script and locking script are concatenated and executed (P2SH and Segwit are exceptions). For example, if someone locked a transaction output with the locking script +"3 ADD 5 EQUAL"+, we could spend it with the unlocking script "+2+" in a transaction input. Anyone validating that transaction would concatenate our unlocking script (+2+) and the locking script (+3 ADD 5 EQUAL+) and run the result through the Bitcoin Script execution engine. They would get +TRUE+ and we would be able to spend the output.
Using a simplified model, for validation, the unlocking script and locking script are concatenated and executed (P2SH and SegWit are exceptions). For example, if someone locked a transaction output with the locking script +"3 ADD 5 EQUAL"+, we could spend it with the unlocking script "+2+" in a transaction input. Anyone validating that transaction would concatenate our unlocking script (+2+) and the locking script (+3 ADD 5 EQUAL+) and run the result through the Bitcoin Script execution engine. They would get +TRUE+ and we would be able to spend the output.
Obviously, this simplified example would make a very poor choice for locking an actual Bitcoin output because there is no secret, just basic arithmetic. Anyone could spend the output by providing the answer "2". Most locking scripts therefore require demonstrating knowledge of a secret.
Obviously, this simplified example would make a very poor choice for locking an actual Bitcoin output because there is no secret, just basic arithmetic. Anyone could spend the output by providing the answer "2." Most locking scripts therefore require demonstrating knowledge of a secret.
==== Locking to a Public Key (Signature)
The simplest form of a locking script that requires a signature. Let's consider Alice's transaction that pays Bob 50,000 satoshis. The output Alice creates to pay Bob will have a locking script requiring Bob's signature and would look like this:
The simplest form of a locking script is one that requires a signature. Let's consider Alice's transaction that pays Bob 50,000 satoshis. The output Alice creates to pay Bob will have a locking script requiring Bob's signature and would look like this:
[[bob_locking_script]]
.A locking script that requires a digital signature from Bob's private key
@ -286,7 +299,7 @@ The simplest form of a locking script that requires a signature. Let's consider
The operator CHECKSIG takes two items from the stack: a signature and a public key. As you can see, Bob's public key is in the locking script, so what is missing is the signature corresponding to that public key. This locking script can only be spent by Bob, because only Bob has the corresponding private key needed to produce a digital signature matching the public key.
To unlock this locking script shown in, Bob would provide an unlocking script containing only his digital signature:
To unlock this locking script, Bob would provide an unlocking script containing only his digital signature:
[[bob_unlocking_script]]
.An unlocking script containing (only) a digital signature from Bob's private key
@ -294,7 +307,7 @@ To unlock this locking script shown in, Bob would provide an unlocking script co
<Bob Signature>
----
In <<locking_unlocking_chain>> you can see the locking script in Alice's transaction (in the output that "pays" Bob) and the unlocking script (in the input that "spends" that output) in Bob's transaction.
In <<locking_unlocking_chain>> you can see the locking script in Alice's transaction (in the output that pays Bob) and the unlocking script (in the input that spends that output) in Bob's transaction.
[[locking_unlocking_chain]]
.A transaction chain showing the locking script (output) and unlocking script (input)
To validate Bob's transaction, a Bitcoin node would do the following:
* Extract the unlocking script from the input (+<Bob Signature>+)
* Extract the unlocking script from the input (+<Bob Signature>+).
* Look up the outpoint it is attempting to spend (+a643e37...3213:0+). This is Alice's transaction and would be found on the blockchain.
* Extract the locking script from that outpoint (+<Bob PubKey> CHECKSIG+)
* Concatenate into one script, placing the unlocking script in front of the locking script (+<Bob Signature> <Bob PubKey> CHECKSIG+)
* Execute this script on the Bitcoin Script execution engine to see what result is produced
* Extract the locking script from that outpoint (+<Bob PubKey> CHECKSIG+).
* Concatenate into one script, placing the unlocking script in front of the locking script (+<Bob Signature> <Bob PubKey> CHECKSIG+).
* Execute this script on the Bitcoin Script execution engine to see what result is produced.
* If the result is +TRUE+, deduce that Bob's transaction is valid because it was able to fulfill the spending condition to spend that outpoint.
==== Locking to a Hash (Secret)
Another type of locking script, one that is used in the Lightning Network, is a _hash lock_. In order to unlock it you must know the secret _pre-image_ to the hash.
Another type of locking script, one that is used in the Lightning Network, is a _hashlock_. To unlock it, you must know the secret _preimage_ to the hash.
To demonstrate this, let's have Bob generate a random number +R+ and keep it secret.
@ -327,7 +340,7 @@ H = SHA256(1833462189) =>
H = 0ffd8bea4abdb0deafd6f2a8ad7941c13256a19248a7b0612407379e1460036a
----
Now, Bob gives the hash +H+ we calculated above to Alice, but keeps the number +R+ secret. Recall, that because of the properties of cryptographic hashes, Alice can't "reverse" the hash calculation and guess the number +R+.
Now, Bob gives the hash +H+ we calculated previously to Alice, but keeps the number +R+ secret. Recall that because of the properties of cryptographic hashes, Alice can't "reverse" the hash calculation and guess the number +R+.
Alice creates an output paying 50,000 satoshi with the locking script:
@ -335,13 +348,13 @@ Alice creates an output paying 50,000 satoshi with the locking script:
HASH256 H EQUAL
----
Where +H+ is the actual hash value (+0ffd8...036a+) that Bob gave to Alice.
where +H+ is the actual hash value (+0ffd8...036a+) that Bob gave to Alice.
Let's explain this script:
The HASH256 operator pops a value from the stack and calculates the SHA256 hash of that value. Then it pushes the result onto the stack.
The +H+ value is pushed onto the stack and then the +EQUAL+ operator checks if the two values are the same and pushes +TRUE+ or +FALSE+ onto the stack accordingly.
The +H+ value is pushed onto the stack, and then the +EQUAL+ operator checks if the two values are the same and pushes +TRUE+ or +FALSE+ onto the stack accordingly.
Therefore, this locking script will only work if it is combined with an unlocking script that contains +R+, so that when concatenated we have:
@ -351,23 +364,23 @@ R HASH256 H EQUAL
Only Bob knows +R+, so only Bob can produce a transaction with an unlocking script revealing the secret value +R+.
Interestingly, Bob can give the +R+ value to anyone else, who can then spend that Bitcoin. This makes the secret value +R+ almost like a bitcoin "voucher", since anyone who has it can spend the output Alice created. We'll see how this is a useful property for the Lightning Network!
Interestingly, Bob can give the +R+ value to anyone else, who can then spend that Bitcoin. This makes the secret value +R+ almost like a bitcoin "voucher," since anyone who has it can spend the output Alice created. We'll see how this is a useful property for the Lightning Network!
[[multisig]]
==== Multisignature Scripts
The Bitcoin scripting language provides a multisignature building block (primitive), that can be used to build escrow services and complex ownership configurations between several stakeholders. An arrangement that requires multiple signatures to spend Bitcoin is called a _multisignature scheme_, further specified as an _K-of-N_ scheme, where:
The Bitcoin Script language provides a multisignature building block (primitive), that can be used to build escrow services and complex ownership configurations between several stakeholders. An arrangement that requires multiple signatures to spend Bitcoin is called a _multisignature scheme_, further specified as a _K-of-N_ scheme, where:
* N is the total number of signers identified in the multisignature scheme, and
* K is the _quorum_ or _threshold_ - the minimum number of signatures to authorize spending.
* _N_ is the total number of signers identified in the multisignature scheme, and
* _K_ is the _quorum_ or _threshold_: the minimum number of signatures to authorize spending.
The script for an K-of-N multisignature is:
The script for an __K__-of-__N__ multisignature is:
----
K <PubKey1> <PubKey2> ... <PubKeyN> N CHECKMULTISIG
----
where N is the total number of listed public keys (Public Key 1 through Public Key N) and K is the threshold of required signatures to spend the output.
where _N_ is the total number of listed public keys (Public Key 1 through Public Key _N_) and _K_ is the threshold of required signatures to spend the output.
The Lightning Network uses a 2-of-2 multisignature scheme to build a payment channel. For example, a payment channel between Alice and Bob would be built on a 2-of-2 multisignature like this:
@ -375,7 +388,7 @@ The Lightning Network uses a 2-of-2 multisignature scheme to build a payment cha
2 <PubKey Alice> <PubKey Bob> 2 CHECKMULTISIG
----
The preceding locking script can be satisfied with an unlocking script containing a pair of signatures:footnote:[The first argument (0) does not have any meaning but is required due to a bug in Bitcoin's multisignature implementation. This issue is described in Mastering Bitcoin, Chapter 7.]
The preceding locking script can be satisfied with an unlocking script containing a pair of signatures:footnote:[The first argument (0) does not have any meaning but is required due to a bug in Bitcoin's multisignature implementation. This issue is described in _Mastering Bitcoin_, https://github.com/bitcoinbook/bitcoinbook/blob/develop/ch07.asciidoc[Chapter 7].]
----
0 <Sig Alice> <Sig Bob>
@ -390,30 +403,30 @@ A multisignature locking script can be represented by a Bitcoin address, encodin
==== Timelock Scripts
Another important building block that exists in Bitcoin and is used extensively in the Lightning Network is a _timelock_. A timelock is a restriction on spending that requires that a certain time or block height has elapsed before spending is allowed. It is a bit like a post-dated check drawn from a bank account that can't be "cashed" before the date on the check.
Another important building block that exists in Bitcoin and is used extensively in the Lightning Network is a _timelock_. A timelock is a restriction on spending that requires that a certain time or block height has elapsed before spending is allowed. It is a bit like a post-dated check drawn from a bank account that can't be cashed before the date on the check.
Bitcoin has two levels of timelocks: transaction-level timelocks and output-level timelocks.
A transaction-level timelock is recorded in the transaction `nLockTime` field of the transaction and prevents the entire transaction from being accepted before the timelock has passed. Transaction-level locktimes are the most commonly used lock time mechanism in Bitcion today.
A _transaction-level timelock_ is recorded in the transaction `nLockTime` field of the transaction and prevents the entire transaction from being accepted before the timelock has passed. Transaction-level timelocks are the most commonly used timelock mechanism in Bitcoin today.
An output-level timelock is created by a script operator. There are two types of output timelocks: _absolute timelocks_ and _relative timelocks_.
An _output-level timelock_ is created by a script operator. There are two types of output timelocks: absolute timelocks and relative timelocks.
Output-level absolute timelocks are implemented by the operator +CHECKLOCKTIMEVERIFY+, which is often shortened in conversation as _CLTV_. Absolute timelocks implement a time-constraint with an abolute timestamp or blockheight, expressing the equivalent of "not spendable before block 800,000".
Output-level _absolute timelocks_ are implemented by the operator +CHECKLOCKTIMEVERIFY+, which is often shortened in conversation as _CLTV_. Absolute timelocks implement a time-constraint with an abolute timestamp or blockheight, expressing the equivalent of "not spendable before block 800,000."
Output-level relative timelocks are implemented by the operator +CHECKSEQUENCEVERIFY+, often shortened in conversation as _CSV_. Relative timelocks implement a spending constraint that is relative to the confirmation of the transaction, expressing the equivalent of "can't be spent until 1024 blocks after confirmation".
Output-level _relative timelocks_ are implemented by the operator +CHECKSEQUENCEVERIFY+, often shortened in conversation as _CSV_. Relative timelocks implement a spending constraint that is relative to the confirmation of the transaction, expressing the equivalent of "can't be spent until 1,024 blocks after confirmation."
[[conditional_scripts]]
==== Scripts with Multiple Conditions
One of the more powerful features of Bitcoin Script is flow control, also known as conditional clauses. You are probably familiar with flow control in various programming languages that use the construct +IF...THEN...ELSE+. Bitcoin conditional clauses look a bit different, but are essentially the same construct.
At a basic level, bitcoin conditional opcodes allow us to construct a locking script that has two ways of being unlocked, depending on a +TRUE+/+FALSE+ outcome of evaluating a logical condition. For example, if x is +TRUE+, the locking script is A ELSE the locking script is B.
At a basic level, bitcoin conditional opcodes allow us to construct a locking script that has two ways of being unlocked, depending on a +TRUE+/+FALSE+ outcome of evaluating a logical condition. For example, if x is +TRUE+, the locking script is A +ELSE+ the locking script is B.
Additionally, bitcoin conditional expressions can be "nested" indefinitely, meaning that a conditional clause can contain another within it, which contains another, etc. Bitcoin Script flow control can be used to construct very complex scripts with hundreds or even thousands of possible execution paths. There is no limit to nesting, but consensus rules impose a limit on the maximum size, in bytes, of a script.
Additionally, bitcoin conditional expressions can be _nested_ indefinitely, meaning that a conditional clause can contain another within it, which contains another, etc. Bitcoin Script flow control can be used to construct very complex scripts with hundreds or even thousands of possible execution paths. There is no limit to nesting, but consensus rules impose a limit on the maximum size, in bytes, of a script.
Bitcoin implements flow control using the +IF+, +ELSE+, +ENDIF+, and +NOTIF+ opcodes. Additionally, conditional expressions can contain boolean operators such as +BOOLAND+, +BOOLOR+, and +NOT+.
Bitcoin implements flow control using the +IF+, +ELSE+, +ENDIF+, and +NOTIF+ opcodes. Additionally, conditional expressions can contain boolean operators such as +BOOLAND+, pass:[<span class="keep-together"><code>BOOLOR</code></span>], and +NOT+.
At first glance, you may find the bitcoin's flow control scripts confusing. That is because Bitcoin Script is a stack language. The same way that the arithmetic operation latexmath:[$1 + 1$] looks "backward" when expressed in Bitcoin Script as +1 1 ADD+, flow control clauses in
At first glance, you may find Bitcoin's flow control scripts confusing. That is because Bitcoin Script is a stack language. The same way that the arithmetic operation latexmath:[$1 + 1$] looks "backward" when expressed in Bitcoin Script as +1 1 ADD+, flow control clauses in
Bitcoin also look "backward."
In most traditional (procedural) programming languages, flow control looks like this:
@ -427,7 +440,7 @@ else:
code to run in either case
----
In a stack-based language like Bitcoin Script, the logical condition comes *before* the +IF+, which makes it look "backward," like this:
In a stack-based language like Bitcoin Script, the logical condition comes _before_ the +IF+, which makes it look "backward," like this:
.Bitcoin Script flow control
----
@ -475,11 +488,11 @@ For Bob to redeem this, he would have to choose the second execution path by giv
Bob's unlocking script puts a +0+ on the stack, causing the +IF+ clause to execute the second (+ELSE+) script, which requires Bob's signature.
Because each of the two conditions also requires a signature, Alice can't use the second clause and Bob can't use the first clause, they don't have the necessary signatures for that!
Because each of the two conditions also requires a signature, Alice can't use the second clause and Bob can't use the first clause; they don't have the necessary signatures for that!
Since conditional flows can be nested, so can the +TRUE+ / +FALSE+ values in the unlocking script, to navigate a complex path of conditions.
In <<htlc_script_example>> you can see an example of the kind of complex script that is used in the Lightning Network, with multiple conditionsfootnote:[From BOLT 3: https://github.com/lightningnetwork/lightning-rfc/blob/master/03-transactions.md]. The scripts used in the Lightning Network are highly optimized and compact, to minimize the onchain footprint, so they are not easy to read and understand. Nevertheless, see if you can identify some of the Bitcoin Script concepts we learned about in this chapter:
In <<htlc_script_example>> you can see an example of the kind of complex script that is used in the Lightning Network, with multiple conditions.footnote:[From https://github.com/lightningnetwork/lightning-rfc/blob/master/03-transactions.md[BOLT #3].] The scripts used in the Lightning Network are highly optimized and compact, to minimize the on-chain footprint, so they are not easy to read and understand. Nevertheless, see if you can identify some of the Bitcoin Script concepts we learned about in this chapter:
This quick glossary contains many of the terms used in relation to Bitcoin and the Lightning Network. These terms are used throughout the book, so bookmark this for a quick reference.
address::
Bitcoin addresses compactly encode the information necessary to pay a receiver. A modern address consists of a string of letters and numbers that starts with bc1 and looks like +bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4+. An address is shorthand for a receiver's locking script which can be used by a sender to sign over funds to the receiver. Most addresses either represent the receiver's public key or some form of script that defines more complex spending conditions. The above example is a bech32 address encoding a witness program locking funds to the hash of a public key (See _Pay to Witness Public Key Hash_). There are also older address formats that start with 1 or 3 that use the base58check address encoding to represent public key hashes or script hashes.
Bitcoin addresses compactly encode the information necessary to pay a receiver. A modern address consists of a string of letters and numbers that starts with bc1 and looks like +bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4+. An address is shorthand for a receiver's locking script which can be used by a sender to sign over funds to the receiver. Most addresses either represent the receiver's public key or some form of script that defines more complex spending conditions. The preceding example is a bech32 address encoding a witness program locking funds to the hash of a public key (See _Pay to Witness Public Key Hash_). There are also older address formats that start with 1 or 3 that use the base58check address encoding to represent public key hashes or script hashes.
Asymmetric Cryptographic System::
@ -29,7 +29,7 @@ balance::
See _capacity_.
bech32::
Bech32 refers to a generic check-summed base32-encoded format featuring strong error-detection guarantees. While bech32 was originally developed to be used as the address format for native Segwit outputs (BIP-173), it is also used to encode lightning invoices (BOLT #11). While native Segwit version 0 outputs (P2WPKH and P2WSH) use bech32, higher native Segwit output versions (e.g. Pay-to-Taproot or P2TR) use the improved variant bech32m (BIP-350). Bech32(m) addresses are sometimes referred to as "bc1" addresses, reflecting the prefix of such addresses. Native segwit outputs are more blockspace-efficient than older addresses and therefore may reduce transaction fees for the owner of such an address.
Bech32 refers to a generic check-summed base32-encoded format featuring strong error-detection guarantees. While bech32 was originally developed to be used as the address format for native SegWit outputs (BIP-173), it is also used to encode lightning invoices (BOLT #11). While native SegWit version 0 outputs (P2WPKH and P2WSH) use bech32, higher native SegWit output versions (e.g., Pay-to-Taproot or P2TR) use the improved variant bech32m (BIP-350). Bech32(m) addresses are sometimes referred to as "bc1" addresses, reflecting the prefix of such addresses. Native SegWit outputs are more blockspace-efficient than older addresses and therefore may reduce transaction fees for the owner of such an address.
Bitcoin Improvement Proposal (BIP)::
A proposal that members of the Bitcoin community have submitted to improve Bitcoin. For example, BIP-21 is a proposal to improve the Bitcoin uniform resource identifier (URI) scheme. BIPs can be found at https://github.com/bitcoin/bips.
@ -39,7 +39,7 @@ bitcoin, Bitcoin::
Bitcoin mining::
Bitcoin mining is the process of constructing a block from recent Bitcoin transactions and then solving a computational problem required as proof of work.
It is the process by which the shared bitcoin ledger (i.e. the bitcoin blockchain) is updated and by which new transactions are included in the ledger.
It is the process by which the shared bitcoin ledger (i.e., the bitcoin blockchain) is updated and by which new transactions are included in the ledger.
It is also the process by which new bitcoin is issued.
Every time a new block is created, the mining node will receive new bitcoin created within the coinbase transaction of that block.
@ -64,7 +64,7 @@ BOLT::
capacity::
The capacity of a payment channel is equivalent to the amount of bitcoin provided by the funding transaction.
As the funding transaction is publicly visible on the blockchain, and the channel is announced via the gossip protocol, the capacity is public information.
It does not reveal any information about how much bitcoin each of the channel partners owns in the channel, i.e. the balance.
It does not reveal any information about how much bitcoin each of the channel partners owns in the channel, i.e., the balance.
A high capacity does not guarantee that the channel can be used for routing in both directions.
c-lightning::
@ -88,7 +88,7 @@ coinbase transaction::
The coinbase transaction may claim the block reward and assign it to one or more outputs.
The block reward consists of the block subsidy (newly created bitcoin) and the sum of all transaction fees from transactions included in the block.
Coinbase outputs can only be spent after maturing for 100 blocks.
If the block includes any Segwit transactions, the coinbase transaction must include a commitment to the witness transaction identifiers in an additional output.
If the block includes any SegWit transactions, the coinbase transaction must include a commitment to the witness transaction identifiers in an additional output.
cold storage::
Refers to keeping an amount of bitcoin offline. Cold storage is achieved when Bitcoin private keys are created and stored in a secure offline environment. Cold storage is important to protect bitcoin holdings. Online computers are vulnerable to hackers and should not be used to store a significant amount of bitcoin.
@ -98,14 +98,14 @@ commitment transaction::
Every time a new payment is made or forwarded using the channel, the channel balance will update, and a new commitment transaction will be signed by both parties.
Importantly, in a channel between Alice and Bob, both Alice and Bob keep their own version of the commitment transaction, which is also signed by the other party.
At any point, the channel can be closed by either Alice or Bob if they submit their commitment transaction to the Bitcoin blockchain.
Submitting an older (outdated) commitment transaction is considered "cheating" (i.e. a protocol breach) in the Lightning network and can be penalized by the other party, claiming all the funds in the channel for themselves, via a penalty transaction.
Submitting an older (outdated) commitment transaction is considered "cheating" (i.e., a protocol breach) in the Lightning network and can be penalized by the other party, claiming all the funds in the channel for themselves, via a penalty transaction.
confirmations::
Once a transaction is included in a block, it has one confirmation. As soon as _another_ block is mined on the blockchain, the transaction has two confirmations, and so on. Six or more confirmations are considered sufficient proof that a transaction cannot be reversed.
contract::
A contract is a set of Bitcoin transactions which together result in a certain desired behavior.
Examples are RSMCs to create a trustless, bi-directional payment channel or HTLCs to create a mechanism which allows trustless forwarding of payments through third parties.
A contract is a set of Bitcoin transactions that together result in a certain desired behavior.
Examples are RSMCs to create a trustless, bidirectional payment channel, or HTLCs to create a mechanism that allows trustless forwarding of payments through third parties.
Diffie Hellman Key Exchange (DHKE)::
On the Lightning Network, the Elliptic Curve Diffie-Hellman (ECDH) method is used.
This shared secret may be directly used as a key, or to derive another key.
The key, or the derived key, can then be used to encrypt subsequent communications using a symmetric-key cipher.
An example of the derived key would be the shared secret between the ephemeral session key of a sender of an onion with the node's public key of a hop of the onion as described and used by the SPHINX Mix Format.
Via https://en.wikipedia.org/w/index.php?title=Elliptic-curve_Diffie%E2%80%93Hellman&oldid=836070673
digital signature::
A digital signature is a mathematical scheme for verifying the authenticity and integrity of digital messages or documents.
They can be seen as cryptographic commitments in which the message is not hidden.
Double-spending is the result of successfully spending some money more than once.
@ -143,8 +141,8 @@ ephemeral key::
feature bits::
A binary string that Lightning nodes use to communicate to each other which features they support.
Feature bits are included in many Lightning Messages as well as BOLT 11.
They can be decoded using BOLT 9, and will tell nodes which features the node has enabled, and whether these are backward compatible.
Feature bits are included in many Lightning Messages as well as BOLT #11.
They can be decoded using BOLT #9, and will tell nodes which features the node has enabled, and whether these are backward compatible.
Also known as feature flags.
fees::
@ -166,7 +164,7 @@ global features (field: +globalfeatures+)::
gossip protocol::
Lightning Network nodes send and receive information about the topology of the Lightning Network through gossip messages which are exchanged with their peers.
The gossip protocol is mainly defined in BOLT #7 and defines the format of the _node_announcement_, _channel_announcement_ and _channel_update messages_.
In order to prevent spam, node announcement messages will only be forwarded if the node already has a channel and channel announcement messages will only be forwarded if the funding transaction of the channel has been confirmed by the Bitcoin network.
In order to prevent spam, node announcement messages will only be forwarded if the node already has a channel, and channel announcement messages will only be forwarded if the funding transaction of the channel has been confirmed by the Bitcoin network.
Usually, Lightning nodes connect with their channel partners, but it is fine to connect with any other Lightning node in order to process gossip messages.
A cryptographic hash function is a mathematical algorithm that maps data of arbitrary size to a bit string of a fixed size (a hash) and is designed to be a one-way function, that is, a function which is infeasible to invert.
The only way to recreate the input data from an ideal cryptographic hash function's output is to attempt a brute-force search of possible inputs to see if they produce a match.
From Wikipedia: https://en.wikipedia.org/w/index.php?title=Cryptographic_hash_function&oldid=868055371
hashlocks::
A hashlock is a Bitcoin Script spending condition that restricts the spending of an output until a specified piece of data is revealed. Hashlocks have the useful property that once any hashlock is revealed through spending, any other hashlock secured using the same key can also be spent. This makes it possible to create multiple outputs that are all encumbered by the same hashlock and which all become spendable at the same time.
Hash Time-Locked Contract (HTLC)::
A Hash Time-Locked Contract or HTLC is a Bitcoin Script that consists of hashlocks and timelocks to require that the recipient of a payment either spends the payment prior to a deadline by presenting the has pre-image or the sender can claim a refund after the timelock expires.
On the Lightning Network HTLCs are outputs in the commitment transaction of a payment channel and are used to enable the trustless routing of payments.
A Hash Time-Locked Contract (HTLC) is a Bitcoin Script that consists of hashlocks and timelocks to require that the recipient of a payment either spends the payment prior to a deadline by presenting the has preimage or the sender can claim a refund after the timelock expires.
On the Lightning Network, HTLCs are outputs in the commitment transaction of a payment channel and are used to enable the trustless routing of payments.
invoice::
The payment process on the Lightning Network is initiated by the recipient (payee) who issues an invoice, also known as a _payment request_.
@ -225,7 +222,7 @@ lnd::
It is written in Go. Source code is at https://github.com/lightningnetwork/lnd.
Local features (field: +localfeatures+)::
Localfeatures of a Lightning Network node are the configurable features of direct interest the its peers.
Localfeatures of a Lightning Network node are the configurable features of direct interest to its peers.
They are announced in the `_init_` message of the peer protocol as well as the `_channel_announcement_` and `_node_announcement_` messages of the gossip protocol.
Locktime::
@ -241,12 +238,12 @@ Messaging Layer::
millisatoshi::
The smallest unit of account on the Lightning Network. A millisatoshi is one hundred billionth of a single bitcoin. A millisatoshi is one thousandth of one satoshi. Millisatoshis do not exist on, nor can they be settled on, the Bitcoin network.
Multi-Part Payment (MPP))::
A Multi-Part Payment (MPP), often also referred to as a Multi-Path Payment) is a method for splitting the payment amount into multiple smaller parts and delivering them along one or more paths. Since MPP can send many or all parts over a single path the term Multi-Part Payment is more accurate than Multi-Path Payment. In computer science Multi-Part Payments are modelled as network flows.
multipart payment (MPP)::
A multipart payment (MPP), often also referred to as a multipath payment, is a method for splitting the payment amount into multiple smaller parts and delivering them along one or more paths. Since MPP can send many or all parts over a single path, the term multipart payment is more accurate than multipath payment. In computer science, multipart payments are modeled as network flows.
multisignature::
Multi-signature (multisig) refers to a script that requires more than one signature to authorize spending.
Payment channels are always encoded as mutlisig addresses requiring one signature from each partner of the payment channel.
Multisignature (multisig) refers to a script that requires more than one signature to authorize spending.
Payment channels are always encoded as multisig addresses requiring one signature from each partner of the payment channel.
In the standard case of a two-party payment channel, a 2-of-2 multisig address is used.
node::
@ -261,7 +258,7 @@ network capacity::
Network Connection Layer::
The lowest layer of the Lightning Network Protocol Suite.
Its responsibility is to support internet protocols like IPv4, IPv6, TOR2, and TOR3, and use them to establish a secure cryptographic communication channel as defined in BOLT 8, or to speak DNS for the bootstrapping of the network as defined in BOLT 10.
Its responsibility is to support internet protocols like IPv4, IPv6, TOR2, and TOR3, and use them to establish a secure cryptographic communication channel as defined in BOLT #8, or to speak DNS for the bootstrapping of the network as defined in BOLT #10.
Noise_XK::
The template of the Noise protocol framework to establish an authenticated and encrypted communication channel between two peers of the Lightning Network.
@ -274,7 +271,6 @@ onion routing::
The encrypted data is transmitted through a series of network nodes called onion routers, each of which peels away a single layer, uncovering the data's next destination.
When the final layer is decrypted, the message arrives at its destination.
The sender remains anonymous because each intermediary knows only the location of the immediately preceding and following nodes.
From Wikipedia: https://en.wikipedia.org/w/index.php?title=Onion_routing&oldid=870849217
output::
The output of a Bitcoin transaction, also called an Unspent Transaction Output or UTXO.
@ -293,22 +289,22 @@ P2SH address::
P2SH addresses are Base58Check encodings of the 20-byte hash of a script. P2SH addresses start with a "3". P2SH addresses hide all of the complexity, so that the sender of a payment does not see the script.
Pay To Witness Public Key Hash (P2WPKH)::
P2WPKH is the Segwit equivalent of P2PKH, using a segregated witness. The signature to spend a P2WPKH output is put in the witness tree instead of the scriptSig field. See _Segwit_
P2WPKH is the SegWit equivalent of P2PKH, using a segregated witness. The signature to spend a P2WPKH output is put in the witness tree instead of the scriptSig field. See _SegWit_.
P2WPKH address::
The "native Segwit v0" address format, P2WPKH addresses are bech32 encoded and start with "bc1q"
The "native SegWit v0" address format, P2WPKH addresses are bech32-encoded and start with "bc1q".
Pay To Witness Script Hash (P2WSH)::
P2WSH is the Segwit equivalent of P2SH, using a segregated witness. The signature and script to spend a P2WSH output is put in the witness tree instead of the scriptSig field. See _Segwit_
P2WSH is the SegWit equivalent of P2SH, using a segregated witness. The signature and script to spend a P2WSH output is put in the witness tree instead of the scriptSig field. See _SegWit_.
P2WSH address::
The "native Segwi v0" script address format, P2WSH addresses are bech32 encoded and start with "bc1q"
The "native Segwi v0" script address format, P2WSH addresses are bech32-encoded and start with "bc1q".
Pay To Taproot (P2TR)::
Activating in November 2021, Taproot is a new output type that locks bitcoin to a tree of spending conditions, or a single root condition.
P2TR address::
The Taproot address format, representing Segwit v1, is a bech32m encoded address and starts with "bc1p"
The Taproot address format, representing SegWit v1, is a bech32m encoded address and starts with "bc1p"
payment::
A Lightning payment occurs when bitcoin is transferred within the Lightning Network. Payments are generally not seen on the Bitcoin blockchain.
@ -369,7 +365,7 @@ RIPEMD-160::
Routing Layer::
The fourth Layer of the Lightning Network Protocol Suite operates on top of the Peer-to-Peer layer.
Its responsibility is to define the cryptographic primitives and necessary communication protocol to allow the secure and atomic transport of bitcoin from a sending node to a recipient node.
While BOLT 4 defines the onion format that is used to communicate transport information to remote peers with whom no direct connections exist, the actual transport of the Onions and cryptographic primitives are defined in BOLT 2.
While BOLT #4 defines the onion format that is used to communicate transport information to remote peers with whom no direct connections exist, the actual transport of the Onions and cryptographic primitives are defined in BOLT #2.
topology::
The topology of the Lightning Network describes the shape of the Lightning Network as a mathematical graph. Nodes of the graph are the Lightning nodes (network participants/peers). The edges of the graph are the payment channels.
ScriptSig or signature script is the data generated by a spender, which are almost always used as variables to satisfy a pubkey script.
secret key (aka private key)::
The secret number that unlocks bitcoin sent to the corresponding address. pass:[<span class="keep-together">A secret</span>] key looks like the following:
----
5J76sF8L5jTtzE96r66Sf8cka9y44wdp
JjMwCxR3tzLh3ibVPxh
----
The secret number that unlocks bitcoin sent to the corresponding address. pass:[<span class="keep-together">A secret</span>] key looks like this: +5J76sF8L5j​TtzE96r66Sf8cka9y44wdpJjMwCxR3tzLh3i​bVPxh+.
Segregated Witness, Segwit::
Segregated Witness, or Segwit, is an upgrade to the Bitcoin protocol introduced in 2017 that adds a new witness for signatures and other transaction authorization proofs. This new witness field is exempt from the calculation of the transaction ID, which solves most classes of 3rd-party transaction malleability. Segregated Witness was deployed as a soft fork and is a change that technically makes Bitcoin’s protocol rules more restrictive.
Segregated Witness, SegWit::
Segregated Witness, or SegWit, is an upgrade to the Bitcoin protocol introduced in 2017 that adds a new witness for signatures and other transaction authorization proofs. This new witness field is exempt from the calculation of the transaction ID, which solves most classes of 3rd-party transaction malleability. Segregated Witness was deployed as a soft fork and is a change that technically makes Bitcoin’s protocol rules more restrictive.
SHA::
The Secure Hash Algorithm or SHA is a family of cryptographic hash functions published by the National Institute of Standards and Technology (NIST). The Bitcoin protocol currently uses SHA-256, which produces a 256-bit hash.
@ -411,7 +403,7 @@ SHA::
short channel id (scid)::
Once a channel is established, the index of the funding transaction on the blockchain is used as the short channel id to uniquely identify the channel.
The short channel id consists of 8 bytes referring to 3 numbers.
In its serialized form it depicts these 3 numbers as decimal values separated by the letter **x** (eg. +600123x01x00+)
In its serialized form it depicts these 3 numbers as decimal values separated by the letter **x** (e.g., +600123x01x00+)
The first number (4 bytes) is the block height.
The second number (2 bytes) is the index of the funding transaction with the blocks.
The last number (2 bytes) is the transaction output.
@ -426,13 +418,12 @@ source-based routing::
Source-based routing is fundamentally different to how routing works on the Internet Protocol.
soft fork::
Soft fork, or Soft-Forking Change, is a protocol upgrade that's forwards & backwards compatible so it allows both old nodes and new nodes to continue using the same chain.
Soft fork, or soft-forking change, is a protocol upgrade that's forward- and backward-compatible so it allows both old nodes and new nodes to continue using the same chain.
SPHINX Mix Format::
A particular technique for Onion Routing used in the Lightning Network and invented by George Danezis and Ian Goldberg in 2009.
A particular technique for Onion Routing used in the Lightning Network and invented by https://cypherpunks.ca/~iang/pubs/Sphinx_Oakland09.pdf[George Danezis and Ian Goldberg in 2009].
With the SPHINX Mix Format, each message of the onion package is padded with some random data so that no single hop can estimate how far along the route it has traveled.
While the privacy of the sender and receiver of the payment is protected, each node is still able to return an error message along the path to the originator of the message.
The paper can be found at https://cypherpunks.ca/~iang/pubs/Sphinx_Oakland09.pdf
submarine swap::
A submarine swap is a trustless atomic swap between on-chain Bitcoin addresses and off-chain Lightning Network payments. Just as LN payments use HTLCs that make the final claim on funds conditional on the recipient revealing a secret (hash preimage), submarine swaps use the same mechanism to transfer funds across the on-chain/off-chain barrier with minimal trust. Reverse submarine swaps allow swaps in the opposite direction, from an off-chain LN payment to an on-chain Bitcoin address.
@ -456,7 +447,7 @@ transport layer::
The transport layer provides communication services between computers such as flow control, verification, and multiplexing (to allow multiple applications to work on a computer at the same time).
Unspent Transaction Output (UTXO)::
See _output_
See _output_.
wallet::
A wallet is a piece of software that holds Bitcoin private keys. It is used to create and sign Bitcoin transactions. In the context of the Lightning Network it also holds revocation secrets of old channel state and the latest pre-signed commitment transactions.
@ -464,7 +455,6 @@ wallet::
watchtower::
Watchtowers are a security service on the Lightning network that monitors payment channels for potential protocol breaches.
In the case that one of the channel partners goes offline or loses their backup, a watchtower keeps their own backups and can restore their channel information.
They also monitor the Bitcoin blockchain and can submit a penalty transaction in the case that one of the partners tries to "cheat" by broadcasting an outdated state.
+
Watchtowers can be run by the channel partners themselves, or as a paid service offered by a third party. Watchtowers have no control over the funds in the channels themselves.
They also monitor the Bitcoin blockchain and can submit a penalty transaction in the case that one of the partners tries to "cheat" by broadcasting an outdated state. Watchtowers can be run by the channel partners themselves, or as a paid service offered by a third party. Watchtowers have no control over the funds in the channels themselves.
Some contributed definitions have been sourced under a CC-BY license from the https://en.bitcoin.it/wiki/Main_Page[Bitcoin Wiki], https://en.wikipedia.org[Wikipedia], https://github.com/bitcoinbook/bitconbook[Mastering Bitcoin] or from other open source publications.
Andreas M. Antonopoulos
3 years ago