Skip to main content

​
Why you need watchtowers

Payment channels have a dispute window (default 48 h). During this window:
  • Counterparty submits a stale-nonce close → you need to respond with the latest-nonce voucher.
  • If you’re offline (maintenance, outage, DoS), you can’t respond.
  • A watchtower can respond for you.
Watchtowers are non-custodial — they hold vouchers you’ve signed but cannot forge, reuse, or misdirect them (watchtower).

​
Requirement

Register with 2–3 independent watchtowers. Losing all of them simultaneously is rare; losing one is not. One of the seven accepting-paid-delivery criteria is “watchtowers registered.” Your node’s /health endpoint reports ready only once this is satisfied.

​
How to register

For each watchtower you want to use:
  1. Discover the watchtower — via WatchtowerAnnounce gossip on cdn/global/v1.
  2. Open a cdn/watchtower/v1 QUIC stream.
  3. Send RegisterWatch: 
    RegisterWatch {
    channel_id,
    counterparty_address,
    latest_voucher,
    heartbeat_interval,
}
  4. Receive Ack with watch confirmation and escrow ID.
  5. On every new voucher, send UpdateVoucher { latest_voucher } over the same stream.
The stream stays open for the lifetime of the channel.

​
What to watch

Register every open channel with your watchtowers. A channel without a watchtower has only your in-process dispute monitor as defense — fine if you’re online, unsafe if you’re not.

​
WatchtowerEscrow

On-chain fee accountability:
  1. Prepay fees into escrow. 
    WatchtowerEscrow.deposit(watchtower, amount)
  2. Watchtower submits periodic heartbeats on-chain, each including a BLAKE3 commitment over the set of vouchers they currently hold.
  3. If a heartbeat is missed, you reclaim the corresponding fee via reclaimFees().
  4. If a heartbeat lies (commits to a voucher set they don’t actually hold and later fails to dispute), the on-chain evidence of the commitment lets you prove the failure.

​
Local dispute monitor

Every node runs an in-process dispute monitor that watches the chain for close events against your channels. If you’re online, this handles disputes without external help — watchtowers are defense-in-depth. Configuration: 
[dispute_monitor]
enabled = true
poll_interval_seconds = 30
Tight polling (10–30 s) catches close events quickly. Don’t turn this off.

​
Voucher commitment

When a watchtower heartbeats on-chain with a voucher commitment, they’re publicly stating “I hold these vouchers.” If they later fail to dispute, the commitment is evidence that they had the authority to do so. This is why watchtowers are “non-custodial with accountability” rather than “non-custodial, good luck” — the escrow + heartbeat mechanism gives you a clean slash-your-watchtower-back path.

​
Operational concerns

  • Clock sync. Heartbeats have a freshness window. NTP on both your host and the watchtower’s host is non-negotiable.
  • Peer table recency. Watchtowers live on the same iroh transport as other nodes. Keep your peer table fresh.
  • Re-register after deregistration. If you deregister and re-register your node, re-register with your watchtowers too — old registrations use a stale NodeId.
  • Watchtower diversity. Using two watchtowers owned by the same operator is not real diversity. Check operator addresses before selecting.

​
When watchtowers are abandoned

A watchtower that stops heartbeating is dead. Missed heartbeats are observable on-chain via WatchtowerEscrow events:
  1. Reclaim escrowed fees via WatchtowerEscrow.reclaimFees().
  2. Register with a replacement watchtower.
  3. Update your config to remove the dead one.