HTLC and commitment message flow

The message flow between Alice and Bob (and also between any pair of channel partners) is shown in Figure 9-3:

Figure 9-3. The message flow for HTLC commitment between channel partners

We’ve already seen the commitment_signed and revoke_and_ack in Chapter 7. 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).

Adding an HTLC

Alice wants Bob to accept an HTLC worth 50,200 satoshis to forward to Dina. To do so, Alice must send the details of this HTLC, including the payment hash and amount to Bob. Bob will also need to know where to forward it, which is something we discuss in detail in XREF HERE.

To add the HTLC, Alice starts the flow we saw in Figure 9-3 by sending the update_add_htlc message to Bob.

The update_add_htlc message

Alice sends the update_add_HTLC Lightning message to Bob. This message is defined in BOLT #2 - Peer Protocol - update_add_HTLC, and is shown in ??? below:

[channel_id:channel_id]
[u64:id]
[u64:amount_msat]
[sha256:payment_hash]
[u32:cltv_expiry]
[1366*byte:onion_routing_packet]

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

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®), 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.

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 XREF HERE.

HTLC in commitment transaction

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 XREF HERE. The complete script of an offered HTLC is defined in BOLT #3 - Transactions - Offered HTLC output and is shown in ??? below:

# Revocation
OP_DUP OP_HASH160 <RIPEMD160(SHA256(revocationpubkey))> OP_EQUAL
OP_IF
    OP_CHECKSIG
OP_ELSE
    <remote_HTLCpubkey> OP_SWAP OP_SIZE 32 OP_EQUAL
    OP_IF
        # Redemption
        OP_HASH160 <RIPEMD160(payment_hash)> OP_EQUALVERIFY
        2 OP_SWAP <local_HTLCpubkey> 2 OP_CHECKMULTISIG
    OP_ELSE
        # Refund
        OP_DROP <cltv_expiry> OP_CHECKLOCKTIMEVERIFY OP_DROP
        OP_CHECKSIG
    OP_ENDIF
OP_ENDIF

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”). In the order they appear in the script, these are:

revocation

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.

redemption

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.

refund

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.

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 Figure 9-4, below:

Figure 9-4. Bob’s new commitment with an HTLC output

Alice commits

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 Chapter 7, but now we can understand the rest of the fields. As a reminder, it is shown in ??? below:

[channel_id:channel_id]
[signature:signature]
[u16:num_htlcs]
[num_htlcs*signature:htlc_signature]

The fields num_htlcs and htlc_signature now make more sense:

num_htlcs

This is the number of HTLCs that are outstanding in the commitment transaction. In our example, just one HTLC, the one Alice offered.

htlc_signature

This is an array of signatures (num_htlcs in length), containing signatures for the HTLC outputs.

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 show in Figure 9-5 below:

Figure 9-5. 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 Chapter 7 previously. As a reminder, that message is shown in ???, below:

[channel_id:channel_id]
[32*byte:per_commitment_secret]
[point:next_per_commitment_point]

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 Figure 9-6:

Figure 9-6. 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.

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 Figure 9-7 below:

Figure 9-7. Alice’s new commitment with an HTLC output

As we described in Chapter 7, Alice’s commitment is the mirror-image of Bob’s, as it contains the asymmetric, delayed, revocable construct for revocation and penalty enforcement of old commitments. Alice’s 19,800 satoshi balance (after deducting the HTLC value), is delayed and revocable. Bob’s 70,000 satoshi balance is immediately redeemable.

Next, the message flow for commitment_signed and revoke_and_ack is now repeated, but in the opposite direction. Bob sends commitment_signed to sign Alice’s new commitment and Alice responds by revoking her old commitment.

For completeness sake, let’s quickly review the commitment transactions as this round of commitment/revocation happens.

Bob commits

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 Figure 9-8 below:

Figure 9-8. 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 Figure 9-9 below:

Figure 9-9. Alice has revoked the old commitment

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.

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 BOLT #2 - Peer Protocol - update_fulfill_htlc and is shown in ??? below:

[channel_id:channel_id]
[u64:id]
[32*byte:payment_preimage]

It’s a really simple message:

channel_id

The channel ID on which the HTLC is committed

id

The ID of the HTLC (we started with 0 and incremented for each HTLC on the channel)

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:

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. 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!

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 Figure 9-10 below:

Figure 9-10. The 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 Figure 9-11 below

Figure 9-11. 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 Figure 9-12 below:

Figure 9-12. 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 Figure 9-13 below:

Figure 9-13. Alice and Bob settle the HTLC and update balances