diff --git a/en/ln-07.md b/en/ln-07.md index b37d40c..55c30c3 100644 --- a/en/ln-07.md +++ b/en/ln-07.md @@ -59,25 +59,25 @@ There is a counterintuitive point to note here: the sender of this message does ##### Step1: Alice -> Bob: update_add_htlc(A1) -Let's say Alice sends Bob an `update_add_htlc`. Let's call this HTLC A1 because it's the first one Alice(A) is sending to Bob. If Bob is happy with all the fields in the messag, then he adds the HTLC to his staging area commitment transaction nad Alice marks the HTLC as pending on Bob's side but does not yet add it to her own staging commitment transaction. +Let's say Alice sends Bob an `update_add_htlc`. Let's call this HTLC `A1` because it's the first one Alice(A) is sending to Bob. If Bob is happy with all the fields in the messag, then he adds the HTLC to his staging area commitment transaction nad Alice marks the HTLC as pending on Bob's side but does not yet add it to her own staging commitment transaction. -![add_a1]() +![add_A1]() -Note that neither side has actually committed to this HTLC yet so if Bob is a routing node for this payment, he should not yet send `update_add_HTLC` to the next hop on the route until A1 has been _irrevocably_ committed. An HTLC addition or removal is only considered irrevocably committed once both parties in the channel have committed to the commitment transaction with or without it. +Note that neither side has actually committed to this HTLC yet so if Bob is a routing node for this payment, he should not yet send `update_add_HTLC` to the next hop on the route until `A1` has been _irrevocably_ committed. An HTLC addition or removal is only considered irrevocably committed once both parties in the channel have committed to the commitment transaction with or without it. This is not shown on the simplified diagram, but in reality Alice's main output in Bob's staging commitment transaction (i.e. the `to_remote` output) will now have the value of the added HTLC subtracted (along with the fees to cover the extra output). If the HTLC ends up succeeding then this amount will be added to Bob's output and if it ends up failing, then it will be re-added to Alice's output. ##### Step 2: Alice -> Bob: update_add_htlc(A2) -Even though they have not committed to HTLC A1 yet, this does not prevent them from adding more changes to the staging area. Alice is more than welcome to propose a new HTLC, A2, to Bob: +Even though they have not committed to HTLC `A1` yet, this does not prevent them from adding more changes to the staging area. Alice is more than welcome to propose a new HTLC, `A2`, to Bob: -![add_a2]() +![add_A2]() ##### Step 3: Bob -> Alice: update_add_htlc(B1) -Likewise, Bob can sugges a change, B1, to Alice: +Likewise, Bob can sugges a change, `B1`, to Alice: -![add_b1]() +![add_B1]() #### Committing to the current state @@ -101,7 +101,7 @@ Let's say that Alice sends this message to Bob. Bob will now have all the requir ![commit_sign_1]() -Notice that Alice knew that her signature would need to cover the A1 and A2 HTLCs. This is fine because the [underlying transport](https://github.com/lightning/bolts/blob/master/08-transport.md) is guaranteed to be reliable and ordered meaning that if Bob were to receive Alice's `commitment_signed` message then it means that he definitely received her `update_add_htlc` messages for A1 and A2. Alice and Bob both know that the signature should not cover the B1 HTLC since Alice has not sent an acknowledgement for it yet. +Notice that Alice knew that her signature would need to cover the `A1` and `A2` HTLCs. This is fine because the [underlying transport](https://github.com/lightning/bolts/blob/master/08-transport.md) is guaranteed to be reliable and ordered meaning that if Bob were to receive Alice's `commitment_signed` message then it means that he definitely received her `update_add_htlc` messages for `A1` and `A2`. Alice and Bob both know that the signature should not cover the `B1` HTLC since Alice has not sent an acknowledgement for it yet. Another thing to notice is that Bob now actually has two valid commitment transwactions since he has not yet revoked his previous state. However, he is incentivised to revoke his previous commitment transaction since the HTLCs on the new state are one of the folowing: - Payments to Bob himself meaning that he gains from committing to the new state. If he doesn't commit to the new state, then Alice won't either and so there would still exist a version of a commitment transaction that does not pay Bob his incoming funds. @@ -117,7 +117,7 @@ In response to Alice's `commitment_signed`, Bob sends the `revoke_and_ack` messa - The `per_commitment_secret` provides Alice with the information she needs to be able to spend any revocation path on Bob's previously valid state. See [revocation chapter] for more detail about how revocation works. - The `next_per_commitment_point` gives Alice the information she needs in order to derive the revocation pubkey that will be used in Bob's next commitment transaction. -Once Alice receives this message, Bob's previous commitment transaction has successfully been revoked. Note that this message explicitly acknowledges the `commitment_signed` message sent by Alice and by extension, since message delivery is reliable and ordered, it also implicitly acknowledge the `update_add_htlc` messages that Alice sent for A1 and A2. Alice can therefore finally add A1 and A2 to her staging area commitment transaction since they are no longer pending on Bob's side: +Once Alice receives this message, Bob's previous commitment transaction has successfully been revoked. Note that this message explicitly acknowledges the `commitment_signed` message sent by Alice and by extension, since message delivery is reliable and ordered, it also implicitly acknowledge the `update_add_htlc` messages that Alice sent for `A1` and `A2`. Alice can therefore finally add `A1` and `A2` to her staging area commitment transaction since they are no longer pending on Bob's side: ![8_revoke_1]() @@ -129,17 +129,17 @@ From the last diagram, notice that Alice's and Bob's latest commitment transacti - From Alice's perspective: - if her commitment transaction were to be broadcast, she gets back her original `to_local` amount. - - if Bob's commitment transaction were to be broadcast, then Alice's offered HTLCs (such as A1 and A2) will be on-chain. For offered HTLCs, alice is sending sats _out_, meaning that her `to_local` would be lower. But, if Bob was a routing node for these HTLCs then he would not have forwarded them as they are not yet irrevocably committed meaning that he won't receive the pre-images required to claim these HTLCs and therefore Alice would be able to get her funds back via the timeout path. If Bob was the recipient of these HTLCs, then he would be able to produce the pre-image to claim the HTLCs, but then Alice would see the pre-image on-chain and would be able to claim the incoming HTLCs from their incoming channel and would thus have earned routing fees. + - if Bob's commitment transaction were to be broadcast, then Alice's offered HTLCs (such as `A1` and `A2`) will be on-chain. For offered HTLCs, alice is sending sats _out_, meaning that her `to_local` would be lower. But, if Bob was a routing node for these HTLCs then he would not have forwarded them as they are not yet irrevocably committed meaning that he won't receive the pre-images required to claim these HTLCs and therefore Alice would be able to get her funds back via the timeout path. If Bob was the recipient of these HTLCs, then he would be able to produce the pre-image to claim the HTLCs, but then Alice would see the pre-image on-chain and would be able to claim the incoming HTLCs from their incoming channel and would thus have earned routing fees. - From Bob's perspective: - if Alice's commitment transaction is broadcast, Bob gets back his funds via the `to_remote` output. - - if Bob had to force close via his commitment transaction, then HTLCs offered to him (like A1 and A2) would be on-chain. If Bob was routing these HTLCs, then he would not have forwarded them on since they are not yet irrevocably committed. So he wouldn't be able to claim the success path but that is fine since the funds for these did not come out of his balance. If Bob waas the final destination for these, then he would be able to claim them via the success path. + - if Bob had to force close via his commitment transaction, then HTLCs offered to him (like `A1` and `A2`) would be on-chain. If Bob was routing these HTLCs, then he would not have forwarded them on since they are not yet irrevocably committed. So he wouldn't be able to claim the success path but that is fine since the funds for these did not come out of his balance. If Bob waas the final destination for these, then he would be able to claim them via the success path. ##### Step 6: Alice -> Bob: update_add_htlc(A3) -We want to be very clear about the point that the commitment transactions can remain out of sync indefinitely and that Bob does not need to send `commitment_signed` just because Alice did. So, for the sake of another example, let's say that Alice at this point sends yet another HTLC, A3, to Bob: +We want to be very clear about the point that the commitment transactions can remain out of sync indefinitely and that Bob does not need to send `commitment_signed` just because Alice did. So, for the sake of another example, let's say that Alice at this point sends yet another HTLC, `A3`, to Bob: -![10_add_a3]() +![10_add_A3]() ##### Step 7: Bob -> Alice: commitment_signed @@ -149,7 +149,7 @@ Bob wants to irrevocably commit some of the HTLCs so that he can forward them on ##### Step 8: Alice -> Bob: revoke_and_ack -Just like Bob did previously, Alice responds to the `commitment_signed` with a `revoke_and_ack` in order to revoke her previous state. This also serves as an acknowledgement to Bob that Alice has received and committed to B1 and so Bob can now add B1 to his staging area commitment transaction. +Just like Bob did previously, Alice responds to the `commitment_signed` with a `revoke_and_ack` in order to revoke her previous state. This also serves as an acknowledgement to Bob that Alice has received and committed to `B1` and so Bob can now add `B1` to his staging area commitment transaction. ![12_revoke_2]() @@ -157,9 +157,9 @@ Quick clean up... ![13_clean_up_2]() -At last, we have some irrevocably committed HTLCs! A1 and A2 have been irrevocably committed. B1 and A3, however, have not since they have not yet been committed to by both parties. +At last, we have some irrevocably committed HTLCs! `A1` and `A2` have been irrevocably committed. `B1` and `A3`, however, have not since they have not yet been committed to by both parties. -Let's quickly irrevocably commit B1 and A3 as well. +Let's quickly irrevocably commit `B1` and `A3` as well. ##### Step 8: Alice -> Bob: commitment_signed @@ -193,11 +193,11 @@ In the best case scenario, a HTLC is removed because it is being fulfilled meani ![update_fulfill_htlc]() -In our example, Bob sends Alice the `update_fulfill_htlc` message for HTLC A2. This also demonstrates that HTLCs don't have to be removed in the same order they were added. +In our example, Bob sends Alice the `update_fulfill_htlc` message for HTLC `A2`. This also demonstrates that HTLCs don't have to be removed in the same order they were added. -![20_fulfill_a2]() +![20_fulfill_A2]() -Notice that just like the updates for adding an HTLC, updates for removing an HTLC will also initially be pending on the receiver side until they have been acknowledged by a `revoke_and_ack`. So in our case, Alice removes A2 from her staging area transaction when she receives the `update_fulfill_htlc` (and allocates the HTLC amount to Bob's output) but Bob does not yet remove the HTLC from his staging area transaction. +Notice that just like the updates for adding an HTLC, updates for removing an HTLC will also initially be pending on the receiver side until they have been acknowledged by a `revoke_and_ack`. So in our case, Alice removes `A2` from her staging area transaction when she receives the `update_fulfill_htlc` (and allocates the HTLC amount to Bob's output) but Bob does not yet remove the HTLC from his staging area transaction. Unlike other update messages, there is no need to wait for an HTLC removal to be irrevocably committed if you receive the pre-image for it. After all, you can immediately send the pre-image upstream in order to claim any HTLCs there. @@ -209,9 +209,9 @@ HTLCs can also be removed due to payment failures such as HTLCs timing out or if The reason field is an encrypted blob for the sender of the payme3nt in order to inform them of the failure reason. -After Bob sends Alice the `update_fail_htlc` message for A1, the state looks as follows: +After Bob sends Alice the `update_fail_htlc` message for `A1`, the state looks as follows: -![21_fail_a1]() +![21_fail_A1]() ##### Step 14: Bob -> Alice: update_fail_malformed_htlc(A3) @@ -219,15 +219,15 @@ The final message that can be used to remove an HTLC is the `update_fail_malform ![update_fail_malformed_htlc]() -This message is sent if any hop on the payment route was unable to parse the `onion_routing_packet` it received in `update_add_htlc`. If Bob sends Alice this message for A3, then the state now looks like this: +This message is sent if any hop on the payment route was unable to parse the `onion_routing_packet` it received in `update_add_htlc`. If Bob sends Alice this message for `A3`, then the state now looks like this: -![22_fail_a3]() +![22_fail_A3]() ##### Step 15: Alice -> Bob: update_fulfill_htlc(B1) -Alice also initiates the removal of B1 by sending an `update_fulfill_htlc` to Bob. +Alice also initiates the removal of `B1` by sending an `update_fulfill_htlc` to Bob. -![23_fulfill_b1]() +![23_fulfill_B1]() Let's now clean up the HTLC removals by irrevocably committing them. This will require a few `commitment_signed` - `revoke_and_ack` flows: @@ -271,7 +271,7 @@ Note that with anchor channels, the need to use the `update_fee` messaging is be ### Message retransmission -Something that you may have picked up on in the add/remove HTLC flow is that explicit acknowledgements for the `update_*` messages is delayed until the `commitment_signed`/`revoke_and_ack exchange`. That is ok most of the time since we assume that the underlying transport between the two nodes (see [BOLT8]()) is ordered and reliable. However, if for some reason the connection between the two nodes needs to be re-established for some reason, there will be doubt regarding whether our peer has received the last message that we sent. This is where the `channel_reestablish` message comes in. Upon reconnection, before continuing with the noirmal operation flow, the peers will exchange this message to make sure they are on the same page and to determine which messages they possibly need to re-send to their peer. +Something that you may have picked up on in the add/remove HTLC flow is that explicit acknowledgements for the `update_*` messages is delayed until the `commitment_signed`/`revoke_and_ack` exchange. That is ok most of the time since we assume that the underlying transport between the two nodes (see [BOLT8]()) is ordered and reliable. However, if for some reason the connection between the two nodes needs to be re-established for some reason, there will be doubt regarding whether our peer has received the last message that we sent. This is where the `channel_reestablish` message comes in. Upon reconnection, before continuing with the noirmal operation flow, the peers will exchange this message to make sure they are on the same page and to determine which messages they possibly need to re-send to their peer. ![channel_reestablish]()