Channel disabled

To make a payment in the Lightning Network we need a channel that we can use to transfer data between two or more partners (routing payments). Since the Lightning Protocol is a hot system which requires all concerned nodes to be online to process an operation (unlike Bitcoin):

The fact that (i.e. in a routing payment),
any channel can go offline during the payment can be a cause of failure in that payment processing.

Temporarily disabled channel

Temporarily disabling a channel is similar to our previous cause: channel disabled.

In this case it is marked as temporary, so the node might come back online soon and the channel will be available again (i.e. hardware maintenance).

Permanent node failure

This is the most severe failure in the Lightning Protocol.

Firstly, Lightning doesn't have an explicit notion of wallet and backup. For this reason, if your node goes down for any reason, there is a chance you could lose most of your funds.

From another point of view, every other node that had a channel with you will see its funds locked in the channel for a certain time (the to_self_delay property).

Insufficient channel capacity

This is the most common source of failure in a payment channel.

That means the channel doesn't have enough funds to process the payment.

Let’s say we want to pay a 25_000-sat invoice. We have opened a channel with enough capacity (1_000_000 sats) with node B, and node B has opened a channel with 20_000 sats to our destination.

20_000 sats is less than 25_000 sats, so node B doesn't have enough satoshis to forward our payment to node C.

Incorrect payment details

This is a common cause of payment failure between two people.

It occurs when, in a payment — routing payment — channel, the recipient gets the wrong hash or amount instead of the ones expected.

Insufficient payment fees

The fee set is not enough for a node to process a payment. This can be fixed by increasing the fee for the payment.

Expired HTLC

In the Lightning Network, the Hash Timelocked Contract is one of the most resilient mechanisms to handle complex routing payment failures.

If the payment is not processed before the HTLC timeout expires, the payment fails and the funds are refunded to each owner in the routing payment system.

You can read more about HTLCs here.

Required node feature missing

This failure occurs when a payment requires a specific protocol feature that a node in the routing path doesn’t support.

The Required Node Feature Missing error in the Lightning Network is an important but relatively technical routing failure.

When a Lightning Network payment is being routed, it needs to pass through multiple nodes to reach its destination.
Each node might support different features or capabilities, as the Lightning Network protocol has evolved over time with various upgrades and improvements.

For example:

• Multi-part payments (MPP) require nodes to understand how to handle payment fragments
• HODL invoices require specific timelock handling
• TLV (Type-Length-Value) extension fields for additional payment data
• Anchor outputs for more flexible fee management
• Newer hash functions or cryptographic primitives

This can result from incompatibilities between the versions of the Lightning implementations run by nodes.

Where are MAC and HMAC implemented in the Lightning Protocol?

Let’s start with the basics first.

What are MAC and HMAC?

MAC stands for Message Authentication Code. It is a tag we use to prove that the message we are sending is authentic — not altered — and that it came from the right sender. A MAC is a one-way function, meaning that it is easy to compute the MAC of a message, but it is hard to compute the message from the MAC.

Let’s take an example without and with a MAC.

• Without a MAC

In this context, we have two nodes, Olaniran and John. Since we have an open channel, we have a way to communicate between us. Actually Olaniran can send a message to John, and he can respond back to Olaniran.

Our current configuration looks like:

In this case, we are exposed to rewriting attacks, where an attacker node can intercept the message and rewrite it. This is a problem because we can’t be sure if the message is authentic or not.

• With a MAC

To prevent this, we are going to add a kind of tag to the message. This tag is called a MAC (Message Authentication Code).

But another problem remains: how do we ensure that we pass the message and the key K in the right order so that our partner can verify the authenticity and integrity of our message?

Since MAC(message, key) is different from MAC(key, message), we have to define an order to create the MAC tag.

At this point, we can introduce HMAC, which is a MAC implementation based on hash functions.

HMAC is now here to provide:

• More privacy
• Message integrity and authenticity
• Key integrity and authenticity

Why and where?

From this we can conclude that MAC and HMAC are essentially used to prove the authenticity of communications and messages between nodes.

In Lightning, it covers:

• Message transport
• Onion routing
• Payment channels (channel state)
• Hashed Timelock Contracts (HTLCs)

What is an HTLC?

A Hash Timelocked Contract is basically a contract between two entities (nodes) in the Lightning Network. This contract says:

If you are able to prove to me you made a payment of X satoshis with a secret which hashes to this Hash before X units of time, you can spend these Y >= X satoshis, otherwise, I’ll get back my funds.

Let’s take an example to understand this better. Let’s say I want to send 2300 sats to Fadi but I do not have an open channel with her.

I have an open channel with Ariel and have 10_998 sats as channel capacity. By the pathfinding algorithm, I found the shortest path to Fadi through Ariel.

Our actual configuration looks like:

How does an HTLC work in that configuration?

To send some sats to Fadi I need to get an invoice from her, maybe through her blog or when she sends it to me. The invoice will contain the following information: amount, hash and expiration.

Let’s focus on the hash part. The hash is a hash of the secret which will be used to prove the payment.

Since I use this route found by pathfinding, we will now call it a routed payment, with the route: I -> Ariel -> Velia -> Fadi

I need to make a contract with Ariel to send 2300 sats to Fadi that says:

If he is able to prove he successfully made this transfer with 30s left, he can spend the 3000 sats we both signed in a 2-of-2 multisig address, otherwise I will get back my funds.

In turn, Ariel will sign a contract with Velia to send 2300 sats to Fadi, and if she is able to prove she successfully made this transfer with 20s left, she can spend the 2700 sats they both signed in a 2-of-2 multisig address, otherwise Ariel will get back his funds.

Then Velia will sign a contract with Fadi that says:

You can spend the 2300 sats we both signed in a 2-of-2 multisig address if you give me the secret which hashes to hash with 10s left, otherwise I will get back my funds.

HTLC successful case

Once we have established an HTLC between Fadi and an intermediate node, Velia in our case, if Fadi gives her secret (unique) for this payment hash to Velia before the expiration time, she will be able to spend the 2300 sats. She successfully received our satoshis.

In turn, Velia will give the secret to Ariel before the expiration time, he will be able to spend, and so on… We move backward with the secret from Fadi to me.

HTLC failure case

For any reason, if some node is unable to fulfill its HTLC contract, primarily:

• Every node will get back its own funds
• And all failed HTLCs make the payment fail too.

This is the atomicity of the HTLC. If one node fails to complete the HTLC, the entire payment fails.

Do I need to trust the following nodes?

No, you don’t need to trust the nodes in the path. The HTLC is a trust mechanism: thanks to the 2-of-2 multisig address you lock the funds in, your partner cannot spend your funds without your validation.

As Lightning is a punishment-based system, cheaters risk losing their entire funds in the payment channel used.

HTLCs ensure trustlessness in that way.

What do participants gain?

Remember that the HTLC is a mechanism to ensure the payment is atomic. The participants gain the following:

• Security: the payment is secure, even if one node fails to complete the HTLC,
• Atomicity: the payment is atomic, even if one node fails to complete the HTLC,
• Trustlessness: the payment is trustless, you don’t need to trust the nodes.

And if you remember well, the Y amount in the HTLC definition is greater than or equal to the amount they have to send. So they do not lose money.

They can be rewarded with some extra sats we will call here — some routing fees.