Feedback
Sign in./start

Site navigation

Theme

Learn

  • Roadmaps

Build

  • Projects
  • Developer Tools

Contribute

  • Open Source Projects
  • Issues
  • Reviews
  • First Contribution
  • BountiesSoon
  • Feedback

Prove

  • Builders

Ecosystem

  • Partners
  • Get Funded↗
  • HackathonsSoon
Sign in./start-building

Become an Open Source Builder. Learn. Build. Contribute. Prove.

Feedback welcome — open a GitHub issue.

Learn

RoadmapsStart Building

Build

ProjectsDeveloper Tools

Contribute

Open Source ProjectsIssuesReviewsFirst ContributionSupportFeedback

Prove

Builders Directory

Account

Sign in

Legal

PrivacyTermsCredits

© 2026 Pull // code MIT · curriculum CC BY-SA 4.0

PrivacyTermsCredits

lesson // lightning

Commitment Transactions

Revocation keys, to_local/to_remote outputs, and penalty security.

advanced6 days

Public lesson — sign in to track progress on this roadmap.

./sign-in

On this page

Learning objectives

  • Explain how commitment transactions represent channel balances
  • Describe revocation and penalty incentives
  • Relate anchors and modern fee bumping to force closes

study // plan

Lessons are primers. Start with Step 1 (required reading) when present, then follow the numbered steps in the article. Depth comes from primary sources, labs, reflection, and evidence.

Research on Bitcoin Search

Step 1 // Required reading

Complete these before the numbered steps in the lesson body. Links are listed here once — not repeated below.

  • bookMastering the Lightning Network

    Ch. 7: Payment Channels

Reflection prompts

  1. Explain Commitment Transactions to a teammate without jargon - what problem does it solve?
  2. What would break in production if you misunderstood Commitment Transactions?
  3. Which BOLT (or implementation doc) is the source of truth for this topic, and what did you verify there?

Lab // Commitment security brief

Complete Steps 2–3. Write a half-page brief: what a commitment represents, why old states are revoked, and what a justice/penalty path does. Optionally inspect channel state fields on Polar after a payment.

evidence required

  • ·Half-page brief covering commitment, revocation, penalty
  • ·One sentence on why offline nodes need watchtowers
  • ·Link to Ch. 7 or BOLT3 section you used
  • ·Optional: Polar/CLI channel state after an update
  1. 01

    Worked mental model

    Re-read the diagrams in this lesson once out loud in plain language. If you cannot explain the flow to a friend without jargon, pause and revisit the Mastering Bitcoin / Mastering Lightning chapters linked in Resources. Chapter references are intentional, not decorative.

  2. 02

    Hands-on habit

    Every protocol idea should be paired with one local experiment. That habit turns reading into builder instinct.

    1. Reproduce the happy path on regtest (or Polar for Lightning)
    2. Break it on purpose (wrong fee, expired invoice, offline peer)
    3. Write down what error you saw and which layer produced it (wallet, node, mempool, peer)
  3. 03

    Glossary check

    Pick three terms from this lesson and define them in one sentence each without opening notes. Weak definitions mean the lesson is not finished yet.

  4. 04

    Resource order

    Use Resources in order: narrative book chapter first, then BIP/BOLT for precision, then implementation docs for commands. Jumping straight to RPC flags without the mental model creates brittle knowledge.

Each Lightning channel state is backed by a pair of commitment transactions — pre-signed on-chain settlements either party can broadcast if cooperation fails.

Complete Step 1 // Required reading in the study plan above, then continue here.

Step 2 — Core idea: revoke old bills, punish cheats

If commitments are wrong, someone can steal funds or deadlock value. This is the cryptographic spine of Lightning security.

Analogy: Every time you update the bar tab, you both sign a new “final bill” and destroy the ability to cash an older bill — because an old bill would be fraud and is punishable.

When state advances to n, state n-1 is revoked. Publishing a revoked commitment lets the peer sweep funds via a penalty (justice) transaction.

Loading diagram…

Old commitments are toxic; broadcasting them can forfeit the channel.

Commitment outputs typically pay each side with different conditions. The local party's output often includes a revocation path and a delayed CSV path. Modern channels use anchor outputs so fee bumping a force-close is more reliable under mempool pressure.

Treat updates as a state machine: proposed → signed → committed → previous revoked. Bugs are often off-by-one state indices.

Always watch the chain

Offline nodes can miss revocation windows. Watchtowers exist for this failure mode.

Done when: You can explain why broadcasting an old commitment can forfeit funds.

Step 3 — Security brief (lab)

Write the half-page brief. Optional: after a Polar payment, note any state/balance fields that changed.

Common mistakes

  • Treating commitments as “just accounting” without revocation
  • Ignoring CSV delays on honest force-close
  • Building fee logic without reading anchor behavior for your stack

Done when: Lab evidence (brief + watchtower sentence + source) is complete.

Next lesson

HTLC Mechanics — conditional payments on top of commitments for multi-hop routing.

further reading

  • boltBOLT3 Transactions
  • articleBitcoin Optech: Anchor outputs

progress // sign in

Reading is public. Sign in to mark lessons complete, sync across devices, and unlock your roadmap.

./sign-in-to-track

discussion

Discussion

prevChannel LiquiditynextHTLC Mechanics

On this page

Press Shift + ? for keyboard shortcuts.

Press R to research on Bitcoin Search.

No questions yet — be the first to ask.