The #Bitcoin #Lightning Spec Part 6/8: Onchain Handling
This part of the spec is not about compatibility between nodes at all, but it spells out exactly what your node should do when it sees the funding transaction spent on-chain. I wrote the document originally as I was writing the c-lightning code, to keep all the different possibilities straight. For precision, the spec talks about “unresolved outputs” which must be watched: the first of which is the funding transaction output itself, and then describes how to “resolve” each one: usually by spending it with another transaction.
Remember, re-organizations can change what a node sees, so the spec says an output is considered “irrevocably resolved” only after the resolution is 100 blocks deep; before that you’re supposed to keep watching.
Also, HTLCs on-chain can still be live: we need to wait for timeouts, use the payment preimage if we get it through the normal network, or extract the payment preimage if the other side spends the HTLC.
There are three cases where a funding transaction output can be spent, to quote the spec:
1. The good way (mutual close): at some point A and B agree on closing the channel, they generate a closing transaction (which is similar to a commitment transaction without any pending payments), and publish it on the blockchain (see “BOLT #2: Channel close”).
2. The bad way (unilateral close): something goes wrong, without necessarily any evil intent on either side (maybe one party crashed, for instance). Anyway, one side publishes its latest commitment transaction.
3. The ugly way (revoked transaction close): one of the parties deliberately tries to cheat by publishing an outdated version of its commitment transaction (presumably one that was more in her favor).
There should be no surprises in the spec itself: case #1 is trivial, case #2 involves waiting until HTLCs time out or we know the payment preimage for them, and case #3 involves using our revocation key to take all the funds. There’s a bit of a twist here for accepted HTLCs, you need to send the HTLC-timeout transaction (which may mean waiting) first, then use the revocation key to spend that output.
We carefully ensured that you can spend all commitment transaction outputs in a single transaction in a standard transaction, so no surprising corner cases there. But the penalty code is likely to be unused in practice, so careful testing of that will be necessary; test vectors here will be very important!
