What do Pending HTLC stages mean?

[hazrulnizam]

I had a very expensive force close recently, and in trying to understand what happened I found out that pending HTLCs in the force close have "stages" attributed to them. This can be seen from the output of lncli pendingchannels under pending_htlcs with the index "stage".

Can anyone help me understand what the stages mean?

Why do HTLCs need to be swept on chain two (2) times before it ends up being usable? Once to get it from stage 1 to stage 2, and another time to end up in lnd's Aezeed wallet keyspace.

From what I understand from the spec, once the HTLC UTXO expires, it should be immediately under your control, and you should be able to immediately sweep it into an address you control. Why the intermediate step? Is this an lnd-only behaviour, or do other implementations do the same?

Please help me understand. Apologies if I sound agitated, I am just really disheartened by this very very expensive force close. Felt like giving up and just keep my sats on chain.

[guggero]

The two stages for sweeping HTLCs are a safety mechanism described in the spec. Going on-chain to resolve an HTLC is always painful, especially in this high fee environment. But the main objective of lnd is always safety of funds, even if that might be costly in time critical situations.
There are discussions on how to optimize these cost/reward calculations here: #7673, #7674

[hazrulnizam]

Thank you. I have read the spec again, and I think I sort of get it now. There are 4 scenarios for resolving HTLCs on-chain:

1. Local commitment transaction, locally offered HTLC (outgoing HTLC).
2. Local commitment transaction, remotely offered HTLC (incoming HTLC).
3. Remote commitment transaction, locally offered HTLC (outgoing HTLC).
4. Remote commitment transaction, remotely offered HTLC (incoming HTLC).

Now for cases where the force close was initiated by our node, cases 1 and 2 apply. These are the scenarios where the 2 stages of sweep apply, because the first sweep is to resolve the HTLC, while the second sweep is for finally getting custody of the HTLC.

For cases 3 and 4, where the force close is initiated remotely, our node will not have to sweep two times. Only once is needed to custody the sats.

Is this understanding correct?

[guggero]

This is an area that isn't really my expertise, so take my response with a grain of salt. Also, I can really recommend @ellemouton's deep dive on the topic: https://ellemouton.com/posts/htlc-deep-dive/ (Elle, feel free to correct me here if I'm wrong).
If you take a look here, the HTLC scripts are mostly symmetric between the local and remote commitment TX (except for different keys being involved). So case 1/3 and 2/4 are the same in terms of whether a 2nd level TX is needed.
What it comes down do is whether an HTLC times out or succeeds.
So IIUC:

1. Locally offered HTLC (outgoing, sender HTLC):
   1. Success -> Sweep directly to receiver either with preimage (or with revocation key)
   2. Timeout -> 2nd level HTLC timeout TX after CLTV time lock -> Sweep after CSV time lock (to allow for revocation)
2. Remotely offered HTLC (incoming, receiver HTLC):
   1. Success -> 2nd level HTLC success TX with preimage -> Sweep after CSV time lock (to allow for revocation)
   2. Timeout -> Sweep directly to sender after CLTV time lock (or directly with revocation)

[ellemouton]

for any output on the remote commitment tx that belongs to you - you wont require a second level tx. The second level tx is only ever for the side that owns that commitment tx. So for both outgoing and incoming HTLCs on your (the local party) commitment tx, you will need to go to a second level state to get the timeout/success. But any output that belongs to you on the remote party's commitment tx, you can just sweep directly (after the 1 block CSV if it is an anchor output)

[ellemouton]

so I think both your answers are correct - just wanted to clarify in which cases you (the local party) need to worry about having a second level tx

[hazrulnizam]

Thanks Elle. I think I get it now.