Payment channels: instant, free payments
Two people lock coins once, pay each other instantly and for free as often as they like, and settle on the chain just once. How channels work and how to use them.
A payment channel is a second layer on top of the chain. Two people lock some coins together once, then pay each other as many times as they like, instantly and for free, without touching the chain. They only go back to the chain once, at the end, to settle.
When to use one
- A game or service where a player pays tiny amounts all the time.
- A subscription or pay-per-use service where you pay per second or per request.
- Any pair of people or apps that trade back and forth often.
For a one-off payment, just send it: it is already fast.
How it works
- Open. Alice opens a channel with Bob and locks 10 DZY. Bob can add some of his own. Everything locked is held by the chain.
- Pay off the chain. Each time they pay, they both sign a new state: how much each of them would get if they closed now, plus a number that goes up every time. Nothing is sent to the chain.
- Settle. At the end, they close the channel with the latest state, and the chain pays each of them their share.
A state looks like { nonce: 7, a: 6, b: 9 }: "this is state number 7, Alice gets 6, Bob gets 9". The two amounts must always add up to what is locked.
Closing
| How | What happens |
|---|---|
| Together | Both agree on the final state. Either of them sends it to the chain, with both signatures, and it is paid out at once. |
| Alone | One person starts closing, with the newest state they have (or the original deposits if there is none). The other has one day to show a newer state. After that day, anyone can finish it. |
What stops cheating
Suppose Alice tries to close on an old state where she had more. Bob, who holds the newer signed state, shows it during the day. The chain accepts the state with the higher number and rejects her old one. So:
- Each state needs both signatures, so nobody can invent one.
- A signature covers the channel, the number and both amounts, so it cannot be moved to another channel or changed.
- The amounts must add up to what is locked, so nobody can claim more than exists.
While a channel is closing, check in at least once a day. If you stay away, an old state can win. Keep every newest state you are given.
Use it
# Alice locks 10 DZY in a channel with Bob
node chain/cli.mjs channel open --key alice.json --to <bob's address> --amount 10
# Opened. The channel's id is ch1a2b3c4d5e6f7a8b
# Bob adds 5 DZY of his own
node chain/cli.mjs channel fund --key bob.json --id ch1a2b3c4d5e6f7a8b --amount 5
# Both sign state number 7: Alice 6, Bob 9. Each prints a signature; swap them.
node chain/cli.mjs channel sign --key alice.json --id ch1a2b3c4d5e6f7a8b --nonce 7 --a 6 --b 9
node chain/cli.mjs channel sign --key bob.json --id ch1a2b3c4d5e6f7a8b --nonce 7 --a 6 --b 9
# Close together with both signatures
node chain/cli.mjs channel close --key bob.json --id ch1a2b3c4d5e6f7a8b --nonce 7 --a 6 --b 9 --sig-a <alice's> --sig-b <bob's>
# Or close alone, then update or settle later
node chain/cli.mjs channel start --key alice.json --id ch1a2b3c4d5e6f7a8b --nonce 7 --a 6 --b 9 --sig-a … --sig-b …
node chain/cli.mjs channel update --key bob.json --id ch1a2b3c4d5e6f7a8b --nonce 8 --a 5 --b 10 --sig-a … --sig-b …
node chain/cli.mjs channel settle --key anyone.json --id ch1a2b3c4d5e6f7a8bLook at any channel with node chain/cli.mjs channel show --id <id> or GET /channel/<id>. Once it is settled it is gone.
Costs
Opening, funding, closing and settling each cost the small fee. The payments in between cost nothing at all.
For builders
The text that both sides sign is "dzy-channel:" + canon({ chain, id, nonce, a, b }), exported as channelMessage. A state is valid if both signatures match, the amounts add up, and the number is higher than any shown before. See the developer kit and the channel.* types in the transaction list.