Easier to read with cream paper, a tint, more contrast or larger text? Choose your colours and text, once, for every page.

Free lesson

Payment channels: open, update, punish, close

After this lesson: I can say who can punish a broadcast of a revoked channel state.

65 min lesson2 commandsBitcoin Script lab: timelocks, multisig, Miniscript and Taproot on a regtest node

A tab you settle at the end

Two friends share a long train journey and keep paying each other for snacks. They write each change on a card and settle once at the end.

A payment channel does that with Bitcoin. Only the opening and the closing go on chain. Every payment in between is a new signed state the two keep to themselves.

By the end of this lesson

Note

I can say who can punish a broadcast of a revoked channel state.

Key words

WordWhat it meansExample
Payment channeltwo people paying each other off chain
Funding transactionthe on-chain output both must sign to spenda 2-of-2 multisig
Commitmenta signed transaction holding the current balances
Revocationhanding over a secret that cancels an old state
Penaltytaking every sat from somebody who broadcast an old state
Watchtowera service that watches the chain for old states

The cells students fill in are left blank in this preview.

A model, not a Lightning node

Note

No Lightning node runs in this lab. The scripts here run paychan.py, a short Python model of a channel's rules. The 2-of-2 lock and the timelocks behind it are the ones you met in lessons 2 and 3.

Open once, then update off chain

Alice puts 100,000 sats into a 2-of-2 output with Bob. That funding transaction is the only thing on chain while the channel is open.

Each payment is a new commitment: a transaction spending the funding output with new balances, signed by both. Either of them could broadcast it at any time. They keep it and carry on.

Open a channel and make three payments

Command
docker exec jupyter python3 steps/channel.py

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Worked example: the states the model printed

StateAliceBobStatus
01000000revoked
17000030000revoked
25000050000revoked
34500055000latest
Close together4500055000paid at once, no wait

The cells students fill in are left blank in this preview.

Try it: a channel as a list

Code: python
# A channel of 60,000 sats. Each payment makes a new state.
states = [(60000, 0)]          # (alice, bob)
for sats in (10000, 15000):
    alice, bob = states[-1]
    states.append((alice - sats, bob + sats))

for n, (alice, bob) in enumerate(states):
    print("state", n, "alice", alice, "bob", bob)

latest = len(states) - 1
print("revoked states:", list(range(latest)))
# Add a payment of 5000 from Bob back to Alice. Which states are revoked now?

Revoking an old state

State 0 gave Alice everything. What stops her broadcasting it after paying Bob? Each commitment pays the broadcaster's own share only after a delay, here 144 blocks.

When a new state is signed, each side hands over a secret for the old one. With that secret, the other side can take the broadcaster's share during the delay.

Broadcast an old state, watched and unwatched

Command
docker exec jupyter python3 steps/cheat.py

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Worked example: who gets the 100,000 sats

What happenedAliceBobWait
Alice broadcasts state 0, Bob watches0100000punished at once
Alice broadcasts state 0, Bob is away1000000144 blocks, and the cheat works
Bob broadcasts the latest state7000030000Bob waits 144 blocks

The cells students fill in are left blank in this preview.

A common mistake

Warning

Many people think every channel payment is recorded on chain. Only the opening and the closing are. The payments in between are signed states the two people hold, which is why each must watch the chain or pay a watchtower to.

About this lab and its source: Bitcoin Script lab: timelocks, multisig, Miniscript and Taproot on a regtest node

Teaching a class? Set this module for your students with a teacher guide, marked assignments and a lab for every student.